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Assembly Lab 


Help! An Easy to use Help function “sm Link 


| John Holder 
SQ) Blue Lake, СА 


Volume 5, Number 1 


What's this all about? 

This article will show you a way of presenting a Help 
function (hereafter called DoHelp) for any of your programs that 
is very easy to implement and use. DoHelp must be XREF'ed 
(XREF DoHelp) at the beginning of the source file that calls it. 
TouseitIjustadda *Help...' menu inanappropriate place in your 
application (I put it right below the standard ‘About Applica- 
tion...' menu item in the apple menu). Call it by simply doing a 
BSR DoHelp when the item has been selected by the user. 

DoHelp was created with the Macintosh 68000 Develop- 
ment System. First assemble the file ‘DoHelp.Asm’ , then run the 
linker on your applications Linker file to Link DoHelp with the 
rest of your code, and finally run RMaker on your Rmaker file. 
You can create the needed ‘help’ resources with ResEdit (or 
whatever you prefer) and add them to your applications resource 
file. “YourApp.Link’ & ‘YourApp.R’ are shown as examples of 
how you link your applications code with DoHelp's code. 

The way DoHelp works is to show a list of resource names 
(a Help topic list created by showing the names of each ‘help’ 
resource in numeric order) using the List Manager. This makes 
adding and editing Help topics very easy, by using ResEdit or 
compiling the needed resources with RMaker. The user can click 
on any name to access its contents, which is displayed in a 
scrollable text window (which temporarily replaces the list of 
Help topics). When the user is done reading this, he can click on 
the button or within the text itself to return to the Help topics. 
From here he can choose to look at another topic or select the 
"Done with Help' button to return to the application. 


Why? 

I wrote DoHelp to put into my latest shareware application 
called ‘Form Ш”. I wanted to keep it as generic as possible so I 
could use it for any other applications that I might create in the 
future. I made it so the calling application wouldn’tneed toknow 
anything specific about the help but would just have to call it 
when the user needs it. It handles everything else. 


What's happening , step by step. 

First, all files needed are Included at the beginning and a 
couple of often used routines for saving and restoring the regis- 
ters are defined as Macros. A few standard EQUates are also 
defined along with some values used by the List Manager. The 
last EQUate is the resource ID# of the DLOG used to display the 
Help function. Finally the DoHelp routine is XDEF’ed so the 
Linker will know what the heck is going on when it’s being linked 
to the code that calls it! 

Now a dialog box is created, the default button is hilighted, 


and we jump to the routine to set up the list of named ‘help’ 
resources. To accomplish this, we first calculate the useable 
width of the cells used in the list by checking the size of the User 
Item’s rectangle (right-left-scrollbarwidth = widthofcells) of the 
Help dialog box (item #2 in this DLOG). Then we create a new 
list with _LNew and set its selflags field to allow only one item 
to be selected at a time. 

The routine to add each named ‘help’ resource is then called. 
We count how many resources of this type there are with 
_CountResources and set list drawing off so it won’t show each 
item as it’s being added to the list. Starting from the last resource 
we cycle through all the resources and add their names to the list 
with _LAddRow & _LSetCell. After the last resource (the 
resource id#1 since we’re adding in reverse) has been put in the 
list, we exit the loop and turn list drawing on and update the list 
to draw it. 

The Dialog filter 

After everything is initialized we go into a loop to watch for 
dialog events. A Dialog Filter is used to handle the List Manager 
events, all other dialog events are handled by _ModalDialog. 
The filter is set up to get values off of the stack (passed by 
_ModalDialog) and create some local variables by using the 
LINK instruction to set up a stack frame. When a click occurs in 
the rectangle of the User Item, _LClick is called to handle 
scrolling or a selection. If a help topic (list item) is clicked on, the 
rectangle is erased, we change the buttons (item #1) name to an 
appropriate message (“Done Viewing’), the cursor is changed to 
the watch cursor and we jump to the Бо Help View routine. 

A new Text Edit record is made with TENew and its text 
size and fontis set. The rectangle around the User Item is framed 
and a scroll bar is created. The selected cells data is retrieved 
using LGetCell to get the name of the resource to read in with 
_GetNamedResource. If the given resource doesn't exist (why 
it wouldn’tI don’t know, but it pays to be safe!) we dispose of the 
TE record and the scroll bar and return to wait for the next event. 
Otherwise, we copy the data in the ‘help’ resource into the Text 
Edit Record and calculate how many lines are in the data. If there 
are more lines than one screenfull, the scroll bar is set up to match 
the amount of lines in the data. Next, we jump to the routine to 
handle text scrolling using another Dialog Filter to handle it. 

If the scroll bar is clicked on, we check which part of the 
scroll has been clicked and handle each part individually. If the 
Thumb is clicked, it’s tracked by _TrackControl until released 
and then we scroll the text according to the difference between 
the controls old and new values. The text is scrolled a line at a 
time or a pagefull at a time depending on the part clicked on. The 
routine Scroll_The_Text figures how many pixels to scroll by 
multiplying the height of a line of text (found in the teLineHite 
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field of the TE record) by how many lines of text are to be 
scrolled. 

When either the button or the content of the text in the dialog 
isclicked, the TE record and the scroll bar are disposed of, the list 
is updated to show it again, we change the buttons name back to 
what it was and we return to watch for more list events. If the user 
clicks on another list item, the whole process starts again. 
Otherwise if the user clicks the button or hits Return, the dialog 
and the list handle are disposed of and control is returned to the 
calling application. 

Credits 

The basis of some of the routines used in DoHelp (such as the 
dialog filters and scroll handling routines) are from Dan 
Weston's extremely useful books "The Complete Book of 
Macintosh Assembly Language Programming" (volumes I and 
II). These books have proved very helpful to my learning to use 
the power of the Mac with Assembly language! 


The End... 

There are many ways that DoHelp could be enhanced. For 
instance, a search feature or a way to print selected help topics 
could be added. The source code is well commented, so anything 
that this article doesn't explain, the comments should be able 
clear up. Well, that’s it, I hope you find this useful enough to use 
in your own applications! 


“FileName: DoHelp.Asm 
:(C) 1988 by John Holder 


2 

¿What it does: 

T generic Help routine: 

: Allows user to click in a list of names (these names are 
“actually the names of ‘help’ resources), and show the data 
“contained in this resource CACSII text), in a scrollable 
;window. Nothing about the dialog Cother than its id®) 15 
"known, so the dialog can be modified without changing this 
: code. To make topics for your help routine, just create 
;NAMED resources of type ‘help’ Clowercase) in your 
“application starting at 1991 and making each 19% one more 
;than the last one. To create the appearance of subtopics 
; just add a few spaces to the beginning of the names of 
;the appropriate 'help' resources. 


;To use this in your application, just make sure you: 
XREF DoHelp 

at the beginning of uour source code and uou call it bu 
“doing 8: 

;  BSR  DoHelp 

;in the appropriate place in your code 


Include Traps.D ; Traps 
Include ToolEqu.D ; ToolBox equates 
Include SysEqu.D ; System equates 
Include FSEqu.D ; File equates 
Include PackMacs.Txt ; PACKage mgr equates 
Include QuickEqu.D ; QDraw equates 
MACRO SaveRegs = 

MOVEM.L A0-A4/D0-D7 , - CSP) 

| 
MACRO RestoreRegs = 

MOVEM.L (SP2*,A0-A4/00-D? 

| 
true equ $0100 
false equ 0 
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nil equ 
arraycolumns equ 
arrayrows equ 
celldepth equ 16 


Q — = 


;depth of Cells in List 


modify EQU 14  ;State of keys and button 
message equ 2 "Message returned in EventRecord 
DialogID equ 2000 ;res 10% of DLOG resource 


XDEF DoHe lp „Define function DoHelp for Linker 


b omea nn 


«««« The beginning of the DoHelp routine ›››› 


LSU i —e,? 


DoHe lp 
saveregs 
CLR.L -(SP) ;space for ptr 
move.w tDialogID, -Csp) 
CLR.L -CSP) ;wstorage 
MOVE L 8-1,-(ӨР) 
_GetNewDialog 
MOVE.L (SP),DialogPtr(A5) ;save ptr 
-SetPort 
;set up stack for my routine 
поуе.1 DialogPtr(A5),-Csp) 
move 81,-Csp) 
bsr HilightDialogButton 
;Set up list of all ‘help’ resources 
bsr SetUpHelpList 
_InitCursor 
Dialog_Loop 
pea DialogsFilter ;use filter to watch 
pea I temNumber CA5) ‘for List mgr events 
-ModalDialog 
WhatsTheHaps21 
¿which item was clicked 
cmp .W #1) I temNumber (A5) 


beq Quit Help 
bra Dialog.Loop 


;click in 'Done..^ but 


; loop until done 


Quit_Help 
;all done, lets get outta here! 
;dispose of the List handle 
томе.1 ListHandle(A5),-Csp) 
-LDispose 
¿kill the dialog 
томе.1 DialogPtr(A5),-(sp) 
_DisposDialog 
;return to calling application! 
restoreregs 
rts 


A Ñ... 


x Dialog Filter to watch for list selections in User Item >> 


DialogsFilter 

;this routine expects parameters to be on the stack (handled 
bu -ModalDialog) 

; PROCEDURE 

:DialogsFilter (thedialog:dialogptr;VAR theEvent:EventRecord 
: VAR itemhit: integer): boolean 


Parambytes SET 12 


tItemHit SET 8 ;8 ptr to an int! 


tEvent SET 12  ;event rec 
tDialog SET 16 ;dialog ptr 
result SET 20  ;result returned 
iPoint SET -4  ;mouse point 
itype SET -6 j;item type 

iHd! SET -10 ;item hand 

iBox SET -18 ;item rect 


localbytes SET -18 


link A6,*localbytes 
saveregs 

,get User Item info (rect) 
томе.1  tDialog(A6),-Csp) 


move 82,-(sp) 

pea iTypeCA6) 

pea iHd1CA6) 

pea 1BoxCA6) 

-GetDItem 

move.]  tevent(A62,A0 

move evtnumCA2),D0 

cmp MKegDwnEvt,DÜ — ¿was it a key down? 

beq CheckForEnterorReturn ;yep! 

томе. Т  tevent(A62,A0 

move evtnum(A0),D0 

cmp *mButDwnEvt , DØ ,мав it a mouse down? 

bne LetDialogHandleIt ;if not, let 
; -ModalDialog 
;handle 

;was it a mouse click in the List Box (User Item)? 

lea evtMouseCAQ), Ad 

lea iPointCA62,A1 

move.1 (CA@)+,CA1)+ 

pea iPointCA6) 

Global ToLoca} 

clr -(5р) 

томе.1 iPointCA6),-Csp) 

реа iBox(A6) 

-PtInRect 

move (sp)+, DØ 

beq LetDialogHandleIt ;not in user item 

bsr HandleListEvent jhandle list event! 


¿we've taken care of the event 

move.)  tItemHitCA6), Ad 

move Bnil, CAB) бей itemhit to nil 
move "true,result(A6) ;stop -ModalDialog 
bra FilterExit ¿from handling! 


LetDialogHandleIt 
move "nil,resultCA6) 
FilterExit 


,restore stack to the way it was before 
jand return 

restoreregs 

unlk A6 

move.| (5р )+, Ад 

adda "parambytes, SP 

jmp CAB) rtis 


(<<< Check for Return or Enter key press ›››› 
CheckForEnterorReturn 


jif the Enter or Return key was pushed, set the itemhit to #1 
jand set result to false so it will be handled by -ModalDialog 


томе. Т tevent(A6),A0 
томе. 1 message(A0),D0 


стр.) %%02,00 ;return key? 

beq SetResult Чер! 

cmp.b %%03,00 ;Enter key? 

beq SetResult Чер! 

bra LetDialogHandleIt ;neither key 
SetResult 


move.] tlitemHitCA6), Ad 

move 81, CAD) ,set itemhit to 1 

move "true,result(A6)  ;let _ModalDialog 
¿handle it 

bra FilterExit 


; ‹‹‹‹ Click in List box! ›››› 


¿handle a click in the list box area 
HandleListEvent 


;-LClick will handle scrolling & selection of list 
j items 

pea iPointCA6) 

-GetMouse 

clr -(sp) 

move.] | iPointCA62,-Csp) 

move tEvent*ModifyCA6), -Csp) 

поуе.1  listhandle(45),-Csp) 


-LClick 

move (sp)+,D0 

сіг.1 TheCe11CA5) ¿start at cell 0,0 
¿for _LGetSelect 

clr -(sp) 

move "true,-Csp) 


pea TheCe11CA5) 

move.]  listhandleCA5),-(Csp) 

-LGetSelect 

move (sp?*,D9 

beq Click_Not_In_Cell ;no cell selected 
,unselect the selected cel] 

move "false,-(sp) 

томе.1 ТһебСе11(А5),-Сер) 

томе.1  listhandle(A5),-(sp) 


-LSetSelect 

,de-activate the list 

move ®false,-Csp) 

томе.1  listhandle(A5),-Csp) 

-LActivate 

bsr Erase Rect ¿Clear topic list 

bsr Set To.DoneViewing ;change button name 
bsr GetandSetWatch ;show watch cursor 
bsr Do_Help_View ¿show text from 


; ‘help’ res 
,re-activate the list 


move 8true,-Csp) 
move.]  listhandle(CA5),-Csp) 
-LActivate 


Click. Not In. Ce11 
rts 


«««« Show the user selected help text »»»» 


wee We We 


¿open the named resource and view its contents 
Do_Help_View 


,Use all of rect except enough room for scroll bar 
,for text window 


bsr Get. Rect Of Item 
lea DispRect(A5),42 

sub 816, RightCA2) 
,create new Text edit record 
сіг.1 -(sp) 

pea DispRect(A5) 

pea DispRect(A5) 

—TENew 


томе.1  (spO*t,TextHand(A5) ¿store handle 
бес TE rec. text to 9 point Monaco 

move.]  TextHand(A52,A1 

move.] (A1),A1 

move 89 teSizeCA1) ;Text Size! 
move.]  TextHand(A52,A1 

томе. (Al),A1 


move "Monaco, teFont(A1) ;lext Font! 
bsr Frame The.Rect 

bsr Get Rect Of Item 

;figure rectangle for scroll bar! 

lea DispRect(A5),42 


move Right(A2),D2 
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sub 815,02 ;scroll bar width 

move D2,Left(A2) ;left = right - 15 

add #1 Right(A2) ;right = right + 1 
;we de because the 
;text rect is 1 
;pixel inside the 
¿User Item’s rect 


pea DispRect(A5) ;expand top & bottom 
move 80 ,-(sp) ;of rect bu 1 pixel 
move 8-1 -(sp) 

_InsetRect 

;create scroll bar! 

clr.] -(sp) 

поуе.1  DialogPtrCA52,-Csp) 

pea DispRectCA5) ;scrolls rect 

move.] #nil,-Csp) 

move #true,-(sp) ;visible 

move #9 -(sp) ; init value 

move #9 -Csp) ;min value 

move "9 -(sp) ;max valueCstert at 0) 
move 8 16,-Csp) ;proc id C16sscroll) 
сіг.1 -(sp) ¿refCon 
_NewControl 


move.] (sp)+,ScrollHand(A5) ;save handle 
move #255 DataLength(A5) ;max length of 

¿data allowed 
;Get the selected cells data 


lea AStr ing(A52, AQ ¿pt to byte after 
add.1 81 AQ ¿length byte 
поуе.1 A@,-Csp) ;put ptr on stack 

pea DataLengthCA5) ¿data length var 


move.) | TheCellCA52,-(Csp) 

поуе.1  ListHandle(A52,-Csp) 
-LGetCe11 

;add length of data to String ptr 
lea ASTr ingCA5), AQ 

move DataLengthCA5 2,00 

move.b D0,C(A0) 

;get the res. & load it 

clr.1 -Csp) 

поуе.1 *’help’,-Csp) 

pea AStr ingCA5) 
-GetNamedResource 

тоуе. 1 (sp),ResHandCAd) 
-LoadResource 

;just to make sure the resource exists! 
move.] | ResHand(A5),A0 


cmp. | #nil,Að ;does res. exist? 
bne А Ok yep, it’s there, go on 
bsr Dumps tuf f ;no such resource! 
rts ¿return 


move.] ResHand(A5),A0 ; lock handle 
-HLock 

;size of handle (text data) 

move.1 ResHand(A5), Ad 

_GetHandleSize 

поуе.1 00,02 02 = length of text data 
;set up Text Edit Record to use ‘help’ data 
move.l | ResHand(A52,A0 ;need text ptr 

move.1 (А0),-(әр) ;convert handle 
move.]  D2,-Csp) ;text length 

move.] TextHand(A5),-Csp) 

-TESetText 

move.]  ResHand(A5),A0 ;unlock handle 
-HUnLock 

;see how many lines of text are in the 

;'help' data 

поуе.1 TextHand(A5),Al 

move.1 (CA1),A1 

move tenLines(A1),d3 ;D3= lines of text! 
;see how many lines fit into rect of user 

;item of dialog box 
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bsr Calc.L ines. In One. Windowful 
move LinesInWind(A5),D1 


sub D1,D3 ;sub enough for a 
cmp $ni1,D3 ¿window full! 
ble Wont.Pass Bottom ;not enough lines 


;to adda scroll bar 
;set the scroll bars max value by the * of lines 
move.]  ScrollHand(CA5), -Csp) 
move D3, -Csp) ,8 of lines 
-SetMaxCt! 


Wont Pass. Bottom 


¿update the text 

pea DispRect(A5) 

томе.1 TextHand(A5),-(sp) 
_TEUpDate 

_InitCursor 

;go watch for text events 

bsr HandleTextEditDialogEvent 
rts ;done with the text, return 


‚‹‹‹‹ Handle events in Dialog box (with text scrolling)! >>> 


HandleTextEdi tDialogEvent 


D_Loop 


saveregs 

pea CheckTextScroll ;filter to watch 
pea I temNumber (A5) ;for text scrolling 
-ModalDialog 


;check which buttons are clicked here 
cmp.w 81 ItemNumber (A5) 
beq Done. With. This ;done viewing text 


;if ItemNumber(A5) = 2, that means the user 
;clicked in the content of the text of the dialog 
¿which is handled the same as clicked the 

; Done Viewing’ button 

cmp.w 82, I temNumber (A5) 

beq Done_With_This ;done viewing text 
bra D_Loop ;keep looping 


««« Finished here with text view >>>) 


one With. This 


bsr DumpStuf f 
restoreregs 
ris 


‹‹‹‹ Dump TE rec. & scroll bar ›››› 


LD 


umpstuf f 


;dispose of text edit record 

томе.1 TextHand(A5),-Csp) 

_TEDispose 

;dispose of Scroll bar 

move.]  ScrollHand(A5),-Csp) 
_DisposControl 

bsr Erase бесі ;erase the rect 
;reset text font & size to System values 
move #12,-(sp) ; 12 point 
_TextSize 

move 80 -(sp) ;Use System Font 
_TextFont 

;re-show the list by causing list update 
MOVE.L — DialogPtrCA52,A1 

поуе.1 | 24(AD,-Csp) 

move.)  ListHandle(CA52,-Csp) 


-LUpdate 

bsr Frame The Rect ;re-frame list rect 
bsr Set. To. DoneWi thHelp 

rts 


«<<< Dialog Filter to watch for text scrolling ›››› 


; FilterExit2 
CheckTextScro11 ,get out of the routine here! 
¿this routine expects parameters to be on the stack (set Up restoreregs 
;by -ModalDialog) unlk A6 
;PROCEDURE move.) (sp)+,A0 
jCheckTextScro11 Cthedialog:dialogptr;VAR theEvent :EventRecord adda ®parambytes, SP 
| VAR itemhit: integer): boolean jmp (А0) rts 
Parambytes SET 12 — Ch 
tItemHit SET 8 ;a ptr to an int! | ‹‹‹‹ Check for Return or Enter key press ›››› 
tEvent SET 12 ;еуепі rec — T — Z —TT.saN 
tDialog SET 16 ;dialog ptr CheckForEnterorReturn2 
result SET 20 ;result returned jif the Enter or Return key was pushed set the itemhit to #1 


jand set result to false so it will be handled! 
iPoint SET -4  ;mouse point 


itype SET -6 ;item type тоуе. 1 teventCA6), Аб 
iHd] SET -10 ;item hand move.] message(A0),D0 
iBox SET -18 ;item rect cmp.b  #$ød,DØ ;return key? 
PartCode SET -20 ;used for scroll beq SetResult2 yep! 
localbytes SET -20 cmp.b $23,080 ;Enter key? 
beq SetResult2  ;yep! 
link A6,* localbytes bra LetDialogHandleIt2 ¿neither key 
saveregs 
move.]  tDialog(A6),-Csp) SetResult2 
move 82 -(sp) томе. tItemHit(A6),A0 
pea iTypeCA6) nove 81,CAD) ,set itemhit to 1 
pea iHd1CA6) move "true,result(A6) ;let modaldialog 
pea 1BoxCA6) bra FilterExit2 ¿handle it 
-GetDItem 
,only rect in user item will be scroll bar that р 
¿this dialog filter handles р ‹‹‹‹ ALL text scrolling routines >>>) 
lea iBox(A6),A2 — DƏ 
move Right(A2),D2 
sub 816,02 ¿Scroll bar width — ——— FQYm—TnT. 
move D2,Left(A2) ;left = right - 16 j ‹‹‹‹ Click in Text Scroll bar »»» 
move.|  tevent(A62,A0 — P - 
move evtnum(A0),D0 Напа1е5сго11 
стр #KeyDwnEvt, DØ — ;was it а key down? pea iPoint(A6) 
beq CheckForEnterorReturn2;uep! —GetMouse 
томе. Т tevent(A6),A0 clr -(sp) 
move evtnumCA2),D0 поуе.1  iPointCA62,-Csp) 
cmp "nButDwnEvt,D0 ¿was it a mouse down? поуе.!  DialogPtr(A5),-Csp) 
bne LetDialogHandleIt2 jif not, let pea WhichContro1CA5) 
; -ModalDialog -FindControl 
¿handle move (sp)+,PartCode(A6) 
¿change mouse pt into local coordinates beq ScrollDone ¿not in anu control 
lea evtMouse(AQ), Ad ¿was click in the scroll bar? 
lea iPointCA6),Al ¿Compare value returned by .FindControl & the 
move.] САЙ )+, СА1)+ ¿scrolls handle we have stored, if they are 
pea iPoint(A6) ;equal then do the scroll routines 
-Global ToLocal move.) 5сго11НапасА5 ),00 
¿was it а mouse click іп the Text Вох scroll move.] WhichControl(A5),D1 
фаг (User Item)? cmp.1 00,01 
сіг -(sp) beq Click In. Scro11 
move.] iPointCA6),-Csp) bra ScrollDone ¿Click not in scroll 
pea 1Box(CA6) 
-PtInRect Click In.Scrol1 
move (sp)+,D0 ¿which part of scroll? 
beq LetDialogHandleIt2 ;not in scroll, cmp я inUpBut ton, Par tCode(A6) 
; let dialog handle beq DoUpSCro11 
bsr HandleScroll  ;go handle text cmp ® inDownBut ton, Par tCode(A6) 
¿scroll event! beq DoDownSCro11 
¿we've taken care of the event cmp я jnPageUp , Par tCode(A6) 
томе. tItemHitCA6), Ad beq DoPageUpSCro11 
move 8111,(А0) бес itemhit to nil cmp tinPageDown,PartCode(A6) 
beq DoPageDownSCro11 
move "irue,result(A6) ;set result to true, cmp 8inThumb,PartCodeCA6) 
bra FilterExit2 ,Stop _ModalDialog beq DoThumb 
¿from handling bra ScrollDone 
LetDialogHandleIt2 ¿handle different parts of scroll 
move Bnil,resultCA6) ;set to nil, let DoUpSCro11 
; -ModalDialog handle clr -(sp) 
pit томе. WhichControl(A5),-Csp) 
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move.1 iPointCA6),-Csp) 


¿value is already 0 


pea UpActionProc sub 81/01 ;sub 1 from scroll val 
-TrackContro] move.)  WhichContro1(A5),-Csp) 
move (вр2%,00 move D1,-(sp) 
bra ScrollDone —SetCtlValue ;set to new value 
move 81/06 ;d6 = how many lines 
DoDownSCrol1 bsr Scroll.The.Text ;to scroll! 
clr -Csp) 
томе.1  WhichControlCA52,-Csp) UpActionDone 
move.] iPointCA6),-Csp) restoreregs 
pea DownAct ionProc unlk A6 
_TrackControl move.1 (sp)+,Al 
move (вр2%,00 adda.w #parambytes,SP 
bra ScrollDone jmp (81) rts 
DoPageUpSCro11 р «««« Handle Down Scroll arrow >>»? 
clr -(sp) — SS ee 
тоуе.1 WhichControl(A5),-Csp) DownAct ionProc 
move.] | iPointCA62,-Csp) ;offsets into A6 stack 
pea PageUpAct ionProc thecontro] set 10 
_TrackContro] pcode set 8 
move (sp )+,00 parambytes set 6 
bra ScrollDone 
link A6, #8 
DoPageDownSCro11 saveregs 
clr -(sp) tst pcodeCA6) 
move.1 WhichControl(A5),-Csp) beq DownAct ionDone 
move.] iPointCA6),-Csp) clr -Csp) 
pea PageDownAct ionProc поуе.1  WhichContro1CA52,-Csp) 
-TrackContro] -GetCtlValue 
move (sp?*,D9 move (вр2%,02 
bra ScrollDone add 81,D2 ;add 1 to scroll val 
clr -(5р) 
¿handle click in thumb of control поуе.1  WhichContro1CA5),-Csp) 
DoThumb -GetMaxCt1 
clr -(5р) move (sp)+,D1 
move.] WhichControl(A5),-(sp) ;don’t scroll past controls max setting! 
-GetCtlValue cmp D1,D2 
move (вр2%,04 04 = old control value bgt DownActionDone 
clr -(5р) поуе.1 WhichControl(A5),-(sp) 


move.] wWhichControl(A5),-(sp) 


move D2,-(sp) 


move.] iPoint(A6),-(sp) -SetCtlValue 
clr.] -(sp) move 8- 1,D6 ;d6 = how many lines 
-TrackContro! bsr Scroll. Тһе. Техі ;to scroll! 
move (sp)+,D0 
clr -(sp) DownAct ionDone 
move.]  WhichControlCA52,-Csp) restoreregs 
-GetCtlValue unlk A6 
move (sp)+,D3 ;03 = new cnt] value move.) (sp)+,Al 
sub 03,04 ;D4-D3=new view value adda.w *parambytes, SP 
move 04,06 jmp (al) rts 
bsr Scroll_The_Text ;5сго11 text selected spot Р 
рга ScrollDone ; «««« Handle PageUp Scroll arrow >>>? 
¿return from HandleScroll s 
ScrollDone PageUpActionProc 
rts ;offsets into A6 stack 
i thecontrol set 10 
; ¿<<< Handle Up Scroll arrow >>>? pcode set 8 
;—— o parambytes set 6 
UpActionProc 


;offsets into A6 stack 
thecontrol set 10 
pcode set 8 
parambytes set 6 


link А6,80 

saveregs 

tst pcode(A6) 

beq UpActionDone 

clr -Csp) 

move.]  WhichControlCA5),-Csp) 

-GetCt Value 

move (sp)+,D1 

beq UpActionDone ;do nothing if control 
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link A6, #8 

saveregs 

tst pcode(A6) 

beq PageUpAct ionDone 

clr -(sp) 

поуе.1  WhichContro1CA5), -Csp) 
_GetCt1Value 

move (sp)+,D1 

move LinesInWind(A5),D0 

sub 81/00 

sub 00,01 

move 00,06 ;d6 = how many lines 


;to scroll! 
sare we going to go before Ist line? 


jif so, figure how manu lines from current position 
¿until Ø (zero) and use that # to scroll text! 


cmp 8ni1,D1 

bge Not. Past. Begin2 

add D1,D6 бей to proper value 

¿for scroll 

move 8ni1,D1 ¿to set ctr] 
Not. Past. Begin2 

томе.  WhichControl(A5),-Csp) 

move D1,-Csp) 

-SetCtlValue 

bsr Scro11. The. Text 
PageUpAct ionDone 

restoreregs 

unlk A6 

move.] (sp)t,Al 

adda.w #parambytes, SP 

jmp (al) jrts 
; «««« Handle PageDown Scroll arrow >>>) 
PageDownActionProc 

;offsets into Аб stack 

thecontrol set 10 

pcode set 8 

parambytes set 6 

link A6, #0 

saveregs 

tst pcode(A6 ) 

beq PageDownAct ionDone 

clr -(sp) 

move.] WhichContro1(A5),-Csp) 

-GetCtlValue 

move (вр2%,07 

move D7,D2 

move LinesInWind(A5),D0 

sub 81,00 

ада 00,02 

neg 00 

move 00,06 ,d6 = how manu lines 


¿to scroll! 
ге we going {о go after last line? 
jif so, figure how many lines from current position 
¿until last line and use that # to scroll text 


clr -(sp) 

томе. Т WhichControl(A5),-Csp) 

_беіМахС+1 

move (sp)+,D3 ;to set ctr] 

cmp 03,02 

ble Not_Past_End 

sub D3,D7 ¿set to proper value 

move D7,D6 ¿for scroll 

move D3,D2 з о set ctrl 
Not. Past End 

томе. 1  WhichContro1CA52,-Csp) 


move D2,-(sp) 


—SetCtlValue 

bsr Scroll_The_Text 
PageDownActionDone 

restoreregs 

unlk A6 

move.1 (sp)+,Al 

adda.w — "parambytes,SP 

jmp Cal) jrts 


) 


; ‹‹‹‹ Do the actual text scrolling >>> 


Scroll_The_Text 
;d6 has how manu lines and which direction to scroll 


; (depending on whether the value is pos. or neg.) 
¿use teLineHite to figure how many pixels to scroll 
‚бу multiplying it with the amount of lines 

сіг.1 02 


move.] TextHand(A5),A2 

move.]  (A25,A2 

move teLineHite(A2),D2 

muls D6,D2 

move 8nil,-C(sp) ;по horiz. scroll 
move D2,-Csp) ;vert. scroll 

move.]  TextHand(A5), -Csp) 

-TESCro11 

rts 


«««« END of all text scrolling routines ›››› 


«««€ How many text lines can fit in user item rect »»» 


‚ 
‚ 
2 
‚ 
C 


alc.L ines. In. One Windowful 


7 


) 


saveregs 
bsr Get Rect Of Item 
сіг.1 04 
Теа DispRect(A5),A2 
move Top(A2),D3 
move Bottom(A2),D4 
sub D3,D4 ;Top-Bottom = how manu 
¿pixels in text view box 
;D4= heighth Cin pixels) 
;of help window 
clr.1 
томе. Т  TextHand(A5),42 
поме. 1 (А2), А2 
move teLineHiteCA2),D5 ;rect heighth 
divu D5,D4 ¿divided by the 
;heighth of one 
;line of text = 
;how many lines 
¿can f it! 
;D4 now = how many lines of text can fit into one 
,Screen of the user item of the dialog box! 
move D4,LinesInWindCA5) 
restoreregs 
rts 


‹‹‹‹ Erase inside of user item rect of dialog »» 


д 
Erase_Rect 
¿erase entire user item rectangle 


2 


2 


б 


2 


$ 


bsr 
pea 


Get Rect.Of Item 
DispRect(A5) 


-EraseRect 


rts 


(<<< 


Get user item rect of dialog ›››› 


et Rect. Of Item 


бес info from User Item #2 


move.|  DialogPtr(A52,-CSP) 
move 82,-(sp) 

pea ItemTypeCA5) 

pea ItemHandleCA5) 

pea DispRect(A5) 
—GetDItem 

rts 


«««€ Change button to say ‘Done Viewing’ ›››› 


et_To_DoneViewing 


bsr Get_Button_Handle 
тоуе.1 ItemHandle(A5),-(sp) 
pea DoneViewing 
—SetCTitle 

rts 
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; «<<< Change button to sau ‘Done with Help’ ›››› 


Set_To_DoneWithHelp 
bsr Get Button. Handle 
move.1  ItemHandleCA5),-(Csp) 


pea DoneString 

-SetCTitle 

rts 
; ‹‹‹‹ Get handle of button in dialog ›››› 
Get. Button. Handle 

;Get the buttons handle (for changing the buttons 

;title) 

поуе.1  DialogPtr(A52,-CSP) 

move 81,-Csp) 

pea ItemTypeCA5) 

pea ItemHandle(A5) 

pea DispRect(A5) 

-GetDItem 

rtis 
<<< Get watch CURSor and display it >>> 
GetandSetWatch 

clr.1 -(sp) 

move ®watchcursor , -(sp) 

~GetCursor 


move.| (sp)+,Ad 
тоуе.1 CA®),-Csp) 
-SetCursor 

rts 


: ¿<<< Frame the user item rect of dialog ›››› 


Frame. The. Rect 
;frame the outside of the user items rectangle 
bsr Get Rect. Of Item 


pea DispRect(A5) ;Inset rect by 1 
move 8-1, -(sp) ¿outward 
move 8-1,-Csp) 
-InSetRect 
pea DispRect(A5) 
-FrameRect 
rts 
i «««€ Hilight A Dialog Button ›››› 


2 
;this routine expects parameters to be on the stack 


; PROCEDURE HilightDialogButton CWPtr: Ptr; WhichItem: Int) 


;Will hilight a button in a dialog box 
HilightDialogButton . 

WindPt SET 1 

WhichI tem SET 8 

parambytes SET 6 


; local variables 


The Type SET -4 ;Vars for _GetDI tem 
TheHandle SET -8 ;handle 
TheRect SET -16 ;item rect 


localbytes SET -16 ;for link 


link A6," localbytes 
saveregs 

томе.1 WindPt(A6),-(SP) 
_SetPort 

move.] WindPt(A6),-(SP) 
move WhichI temCA6),-Csp) 


pea The Type CA6 ) 
pea TheHandle(A6) 
pea TheRect(A6) 
-GetDItem 

move 83,-(sp) 
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move #3,-С5р) 


_PenSize 

pea TheRect (A6) 
move 8-4 -(sp) 
move 8-4 -(sp) 
_InSetRect 

pea TheRectCA6) 
move #16,-Csp) 
move 816,-Csp) 
-FrameRoundRect 
move 81,-Csp) 
move 81,-Csp) 
-PenSize 
restoreregs 

unlk A6 


поме.1 (sp)+,A0 
adda *parambytes, SP 
jmp (A0) rts 


«ccc Set up the dialog box with the help info ›››› 


SetUpHelpList 


2 


2 


saveregs 

bsr Calc-Cell.Width 

bsr Get Rect ОҒ. Item 

;must allow room for the lists scroll bar on the right 
;Side so subtract 15 from the rects right side! 

lea DispRect(A5),A1 

sub #15 rightCAl) 

;set up the arrayrect (for the cells rows and columns) 
;for the List Mgr 


lea arrayrect(A5),a0 
тоуе. 1 80 (А0)% 

move "'arrayRows, (А02% 
move Заггаусо1итп5,(А02% 
move ®celldepth, 00 

swap 


00 
move cellWidth(A5),D0 
¿create a new List 


сіг.1 -(sp) 

pea DispRect(A5) ;list rect! 
pea arrayrect(A5) 

поуе.1 D0,-(sp) ;cell size 

move 8g -(sp) гез id of proc. 


move.]  DialogPtr(A5),-Csp)  ;window ptr 


move.w  "false,-Csp) ,draw it? 

move 8Sfalse,-Csp) ;has grow? 
move 8Sfalse,-Csp) ;horiz scroll? 
move ®true,-Csp) мегі scroll? 
_LNew 


move.] (sp)+,ListHandleCA5) 

;set selflags to allow only one selection at a time! 
тоуе.1 ListHandleCA5), Ad 

томе. (ҮА0),А0 

move.b — *128,selFlags(A0) 

¿put all the ‘help’ names (topics) into the list 


bsr AddHelpNamesToL ist 
restoreregs 
rts 


««« Calculate cell width for list manager ›››› 


Calc Cell Width 


2 


A 


bsr Get Rect. 0f Item 
move DispRect*rightCA52,D2 
move DispRect+lef tCA5),D3 


sub D3,D2 

Sub 816,02 ;allow for scroll 
move D2,cellwidth(A5) ;return value 
rts 


«««€ Add ‘help’ resource names to List ›››› 


pU TY 


ddHelpNamesToL ist 


¿this is a routine to add all ‘help’ resource names 
sto a list 


saveregs 

clr -(sp) 

томе.1  f'^help'^,-Csp) 

-CountResources 

move (sp)+,D4 how many there are 

move D4,D7 

beq None_Here ;if no ‘help’ res’s 
jhere, quit! 

sub 81/04 ¿sub 1 for looping 
¿(the DBRA later) 

move ®false,-Csp) ¿set drawing off 

move.]  ListHandle(A5),-Csp) 

-LDoDraw 


томе.1 8п11,ТһеСе11(А5) ;start with zero cell 
¿set ResLoad off (so resources are not 
,automatically read into memory) 


move *"false,-Csp) 
_Se tResLoad 
AddhelpLoop 
сіг.1 -(sp) 
move.) %’help’,-Csp) 
move D7,-(sp) ;res. id 8 
-GetResource 


move.] (sp),A4 ;leave handle on stack 
,for next routine 

¿get the resources name 

pea ResId(A5) 


pea ResType(A5) 
pea ResNameCA5) 
-GetResInfo 

lea ResNameCA5), A3 
с1г.1 D3 


move.b (A3)+,D3 ;how many chars in 
¿name for later 

sub 81,D7 ,decrement index 8 
07 = the res idt 

;93 = how many characters in string, 


;АЗ = ptr to string data 

,add а new row 

clr -(sp) 

move #1,-С5р) 

move #0,-С5р) 

томе. 1 ListHandle(A5),-(sp) 
-LAddRow 

move (sp)+,D0 


бес the cells data to the resources name 
move.] A3,-(sp) ;points to name 

move D3,-(sp) ;how many chars? 

томе.1 TheCe11(A5),-(sp) 

томе. 1  ListHandle(A5),-Csp) 

-LSetCe11 

dbra D4,AddhelpLoop ;loop until D4 = Ø 
¿set ResLoad back on 


move 8true, -Csp) 

-Se tResLoad 

move #true,-(sp) ;turn drawing on 
move.]  ListHandle(A5),-Csp) 

_LDoDraw 


¿update the list to show it 
MOVE.L  DialogPtr(A52,A1 
move.| 24(A1),-Csp) 
томе.1  ListHandleCA5),-Csp) 
-LUpdate 
bsr Frame. The. Rect 

None Here 
restoreregs 
rts 


; ‹‹‹‹ Constants ›››› 
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DoneString dc.b 14, "Done with Help’ 


align 2 
DoneViewing  dc.b 12, one viewing’ 
Align 2 


4 


; (<<< Global variables ›››› 


WhichControl ds.1 
TextHand 06.1 
ScrollHand 65.1 
DialogPtr ds.1 
LinesInWind ds 

AString ds.b 


1 ;used bu -FindControl 

1 ;TE record Handle 

1 ,Handle of scroll bar 

1 Ptr to Help Dialog 

1 ¿how manu text lines fit in rect 
256 ;Space for a string 


ListHandle  ds.11 Handle to list 

TheCe11 ds.11 ,Used by the List Mgr 
ArrayRect ds.12 ;Rows & columns for List Mgr 
cellwidth ds.w 1 ¿width of cell in list 
DataLength | ds.w1 ¿Var used by -LGetCell 


ItemType ds.11 ,Vars used by —GetDI tem 
ItemHandle 05.11 ;Handle of Dialog Item 
DispRect ds.12 ;Rect of Dialog Item 


ResHand ds.11 ;Handle of а ‘help’ resource 
ResId ds.w 1 ,Vers used by _GetResInfo 10% 
ResType ds.11 jres. type 
ResName ds.b256 ;res. name 


ItemNumber  ds.w 1 ;Item# returned by .ModalDialog 
END 


File name: YourApp.R 

Example .R file for YourApp, which 

is an example application name 

that has been linked with DoHelp. 

Resource iS also an example name, it 
should be the name of a resource file 
containing all of the needed resources for 
YourApp, Including the ‘help’ resources for 
DoHelp which you can create using ResEdit 
This also creates the DLOG & DITL that 
DoHelp needs. 


© зе »* зе з »* »* ым зе зе 


MDS 1: YourApp 


APPLTEST 
File name: YourApp.Link 
Type DLOG Example Link file for 
, 2000 DoHelp & YourApp 
Help YourApp is an example 


96 32 318 476 


dis name, it should be 
visible NoGoAway 


whatever name 


‚ 
‚ 
‚ 
; 
; 
; 
; 
; 


4 you use for your 
0 applications code. 
2000 
/Output YourApp.Code 
Type DITL /Type ‘TEMP’ 
‚ 2000 
3 MDS2 : YourApp 
/Segment 
Button MDS2 :DoHe lp 
232 152 256 288 /Segment 
Done with help 
$ 
userItem 
8 8 200 434 


staticText Disabled 
208 96 224 344 
Click on a Help topic (above) to view. 


INCLUDE MDS2:YourApp .Code 
INCLUDE MDS 1:Resources 


Sel 


cut, 
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Assembly Lab 
Convert PICTs to Regions 


[Ted Cohn has been a long-time Mac enthusiast and used to 
bean Apple ][ hacker. He wrote a professional 6502 debugger for 
the Apple ][ called Bugbyter which Apple sold with its ProDOS 
assembly package. He graduated from UC Berkeley with aB.A. 
іп Computer Science. Since then he has been working at Radius 
Inc., where he designed and wrote Tear-off Menus and a real- 
time magnifier for the Radius Two Page Display.] 


Quickdraw Regions What's This All About? 

Have you ever used a region? If so, have you ever tried cre- 
ating irregularly-shaped ones? A year ago I wanted to write a 
desk accessory that would require several stran gely-shaped 
regions. Unfortunately, I found no simple way to create them 
with the routines Quickdraw provides. Creating a region in 
Quickdraw is procedural: You must call OpenRgn, draw lines, 
rectangles, ovals, etc., and then call CloseRgn to definearegion's 
boundary. This can be a tedious, almost unbearable process if 
you want to create bizarre regions by having to combine simple 
geometric shapes. My goal was to find a way to create regions 
in a non-procedural manner by drawing them with a standard 
paint program. Although Quickdraw does provide some useful 
functions like UnionRgn, DiffRgn, SectRgn and XorRgn, it does 
not provide a routine to converta bitmap into a region —a routine 
I believe should be standard Quickdraw equipment. 

The question arose: how do I turn a bitmap into a region? 
One could develop an algorithm to trace the edges of the bitmap 
and use Quickdraw to add each point individually to the region's 
boundary, but that seemed a bit primitive. The only way to find 
an efficient algorithm was to first understand the region structure 
itself. And as many already know, Apple has never divulged the 
region's structure — certainly cause for some fun detective work. 
I became sidetracked by this fascinating data structure. 

The following explains the region format and my solution to 
the problem of region creation. Listed afterwards is MakeRgn, 
an assembly function to convert a bitmap into a Quickdraw re- 
gion, and PicORgn, an MPW tool which utilizes MakeRgn to 
convert ‘PICT’ resources to “КОМ” resources. 


Let There Be Light! 
This is what Apple thinks we ought to know about regions: 


rgnSize: Integer; 
rgnBBox: Rect; 
rgnData: Mystery; 


Inside Mac, page I-141, states, “A region can be concave or 


convex, can consist of one area or many disjoint areas, and can 
even have ‘holes’ in the middle." A region specifies exactly 
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which pixels lie inside and outside of aclosed boundary. So, how 
does a region represent this boundary? Inside Mac describes only 
the header of the region structure, rgnSize and rgnBBox, which 
are not very interesting. RgnSize specifies the total number of 
bytes in the region data structure while rgnBBox contains the 
region’s bounding rectangle. This is the smallest rectangle that 
will completely enclose the region, that is, each edge of the rec- 
tangle will touch at least one point of the region’s boundary. It 
seems, however, that rgnData was left as an exercise to the devel- 
oper — a complete mystery and a nagging curiosity. 

Now let’s get technical. It turns out that the rgnData 
structure is not as complex as it might seem. A region is like a 
bitmap in that it is arranged into scanlines and is read from left to 
right, top to bottom. This makes sense since regions are used to 
“mask” bitmaps which are also read from left to right, top to 
bottom. Butinstead of containing pixel data, the region need only 
contain boundary information. 

Figure la is a doughnut-shaped picture we would like to 
convert into a region. Let's step through the conversion process. 
If we restrict ourselves to the horizontal dimension for the mo- 
ment, we can isolate the boundary pixels of this bitmap by taking 
the exclusive-OR of itself with its right-shifted copy. Figure 1b 
is the result of this process. Notice that pixels which begin a 
horizontal line segment remain (pixel [5,0] for instance). The 
remaining pixels of each line segment are lost, but we gain an 
extra pixel at the end of the line segment. This additional pixel 
appears because of the XOR function and signifies the end of the 
segment. Therefore, in the horizontal dimension, two pixels are 
used to define the line segment. 

Now we could use horizontal information alone to define 
the boundary, but we would have to store every scanline of the 
region. This would be extremely wasteful in cases where many 
contiguous lines are the same (as with large rectangular win- 
dows). Notice in Figure 1b that lines three and four are equal, 
lines six through eight are equal, and lines ten through eleven are 
equal. 

Redundant information in the vertical dimension is elimi- 
nated by taking an additional XOR of the bitmap in Figure 1b, 
except, we take the XOR of the bitmap with its down-shifted 
copy. Each scanline is replaced by an XOR of itself with the 
previous line. Figure 1с shows the result of this second XOR. 
Notice that lines four, seven, eight and eleven are now blank. 
This means that only the first line of a run of equal lines is 
necessary to define them all. 

The Quickdraw region is basically a list of the points 
(represented by black pixels) in Figure Ic. These points are 
called “inversion points." Why? Well, if we were to read a 
scanline from left to right, they would essentially invert the state 
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(b) 


terminates the scanline. The 
remaining scanlines come 
one after another, each start- 
ing with its vertical coordi- 
nate. When there are no 
more scanlines remaining, a 
final end mark, $7FFF, ter- 
minates the rgnData struc- 
ture. Figure 2 shows the 
entire Quickdraw region 
data corresponding to the 
inversion points of 
Figure 1c. 


Figure 1. Three stages of finding a picture’s inversion points. (a) Source bitmap where black pixels are 


inside the region. (b) Horizontal XOR with right-shifted copy. (c) Final bitmap resulting from 
horizontal and vertical XORs with inversion points ready to be converted to region format. 


of being inside or outside of the region. Unfortunately, this 
definition is not completely accurate. There is a little more to 
inversion points than meets the eye. One must realize that no 
single line of inversion points (except for the first line) can 
reliably specify which pixels lie inside or outside of a particular 
line's boundary. Because the region is not a random access data 
structure like a bitmap, it must be "played back,” line by line, 
starting from the top. The first line of inversion points defines the 
line segment(s) of the top line, but inversion points of successive 
lines do not directly inform us of the region's boundary. Bound- 
ary information provided by inversion points trickles down each 
lineas theregion is processed. This boundary information comes 
in the form of horizontal “markings” which аге set and cleared by 
inversion points. An inversion point on one line can cancel out 
a mark made by an inversion point from a previous line. 

To illustrate, let's unravel the boundary of the second line of 
Figure 1c. The line segment defined on the first line is assumed 
to be the same for the second line, so marks [5] and [10], which 
were set, carried through. The second line contains four inver- 
sion points: [3,1], [5,1], [10,1] and [12,1]. Inversion point [3,1] 
defines the new starting point of the line segment. Point [5,1] 
cancels mark [5] made by the previous inversion point [5,0] so 
the line segment will not end at point [5,1]. The line segment 
might also have ended at point [10,1] if it were not for the 
inversion point [10,1] telling us to cancel mark [10]. The line 
segment then ends at point [12,1]. For line three, only two marks 
carry through: [3] and [12]. The other two were canceled out. 

During runtime, these marks are stored in the form of an 
internalized bitmapped line. The bitmapped line is modified 
from the inversion points that are read in and can be conveniently 
used to plot the bits of the region on the screen or mask a bitmap 
in CopyBits. 

At this point, let me spell out the rgnData structure in detail. 
RgnData is alist of two or more scanlines. Each scanline begins 
with its vertical coordinate. (Every coordinate in the structure is 
a word in length.) Inversion points are then listed from left to 
right by entering their horizontal coordinates one after another. 
Note thatthere are always an even number of inversion points per 
scanline because the region is closed. An end mark, $7FFF, 
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MakeRgn Joins the 
Quickdraw Family 


Since it is desirable to draw a region with a paint program, 
we define the region in bitmap form such that all black pixels in 
a bitmap are logically included in the region and all white pixels 
are logically excluded. MakeRgn (Listing 1) follows the process 
outlined above in converting this bitmap to Quickdraw region 
format. MakeRgn first does a horizontal XOR with its righted 
shifted copy and then does a vertical XOR with its down-shifted 
copy. We could take the vertical XOR first; the order doesn't 
matter. This produces a bitmap with inversion points whose 
coordinates are entered into the rgnData structure. MakeRgn will 
create and return the region handle, so don't call NewRgn first. 
If MakeRgn is provided with an empty bitmap, it will return an 
empty region. It does nothandle Memory Manager errors. If you 
are concerned about heap space, you can test to see if there exists 
a free block which is about one hundred bytes larger than your 
source bitmap. The rgnSize and rgnBBox fields will be calcu- 
lated and filled in too. The coordinates of the rgnBBox will 
reflect the bitmap's bounds rectangle and the location of the 
region within it. 


Tools of the Trade 

Pict2Rgn, an MPW Tool shown in Listing 2, lets one convert 
‘PICT’ resources into ‘RGN ' resources. Listing 3 is the make 
file associated with Pict2Rgn. To use it, place ‘PICT’ resources 
into a resource file and execute Pict2Rgn with that file name. It 
will convert each picture and add its corresponding ‘RGN ' 
resource to that file with the same ID and name as the source 
‘PICT’. The program does not check to see if the resource file 
already contains regions with the same ID's, so make sure it is 
clear of “RGN ' resources before converting pictures. Pic2Rgn 
demonstrates how to open a GrafPort and draw a picture into that 
port. Once drawn, the conversion to region format is done by 
calling MakeRgn with a pointer to the GrafPort's bitmap. 

A nice extension to this tool might be a Region Editor that 
would allow one to graphically manipulate regions and apply 
Quickdraw functions to them. Another would be a Control Editor 
to let one create interesting new controls for dialog boxes. The 
basic method outlined in Pict2Rgn should be helpful in writing 
your own utility or package to use MakeRgn. 
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0000 0000 000F 000F 


TFFF 
0002 0002 0003 000С 000D 7FFF 
0003 0001 0002 000D 000E 7FFF 
0005 0000 0001 0006 0009 000Е 000Ғ 7FFF 
0006 0005 0006 0009 000A 7FFF 
0009 0005 0006 0009 000A 7FFF 
000A 0000 0001 0006 0009 000Е 000Е ТЕРЕ 
000C 0001 0002 000D 000E 7FFF 
0000 0002 0003 000C 000D 7FFF 
ТЕЕЕ 


Figure 2. Region data corresponding to bitmap іп Figure 1с. The region is 156 bytes long. 
The rgnBBox rectangle is (0,0,15,15). RgnData lists each scanline of inversion points 
which begin with the vertical coordinate and end with the constant $7FFF. 


A Tidbit: What a Drag 

If you are interested in dragging outlines of regions, there is 
a faster way than calling FrameRgn continuously. First, make a 
copy of the region, then InsetRgn(theRgnCopy, 1, 1) and 
DiffRgn(theRgn, theRgnCopy, theRgn) to create a region out- 
line. Then call PaintRgn(theRgn) to drag the region outline 
around. FrameRgn is slow because it performs this same process 
every time it is called. 


Any Alternatives? 

Not surprisingly, bitmaps can be used to represent bounda- 
ries too. Like our definition above, we can say that black pixels 
in a bitmap represent the interior of the boundary. Depending on 
the complexity of the boundary, a bitmap can be considerably 
smaller in size than its equivalent Quickdraw region. The region 
data in Figure 2 is 156 bytes long, whereas the bitmap in Figure 
1 is only 30 bytes long! This is because each inversion point 
requires entire word of storage. If there is more than approxi- 
mately one inversion point per word of pixel data, then itis more 
space efficient to use a bitmap to represent the region. Still, 
Quickdraw regions are perfect for use by the Window Manager 
because the regions manipulated are usually rectangular and 
generally large requiring at most several hundred bytes. (Imag- 
ine Quickdraw using entire bitmaps just for region manipula- 
tion!) Thus, the larger, less complex the region, the more space 
efficient itis compared to its bitmap equivalent. On an historical 
note, region data was originally compressed by Quickdraw. 
Regions were generally around one third the size they would be 
today, butregion manipulation was slower because of the on-the- 
fly compression/decompression. Region compression was 
removed before shipping the 128K Mac. While I don't prefer a 
larger region structure, I think Apple was wise in opting for speed 
in the windowing environment — especially now that we have 
megabyte systems instead of 128K Macs to contend with. 


Region Wrap-up 
I hope this utility helps promote the creation of regions for 
new controls and windows. While user interface standards are 
important, I think a little variation wouldn’t hurt. As to Apple’s 
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changing the region format in the future, I have this to say: It is 
easier to design regions non-procedurally than procedurally. If 
the format changes, another routine can be easily created to 
convert a bitmap into a region. In the future, I hope Apple will 
add a similar conversion routine to its graphics repertoire. If you 
use MakeR gn, I would be most interested in hearing about it. My 
AppleLink address is D0959. Happy Macing! 


Listing 1. MakeRgn assembly code. 


MakeRgn.8 


* Written by Ted Cohn, March 1987. 
; Copyright 1988 By Ted Cohn. 

; MakeRgn converts а bitmap image into а Quickdraw region. 

; Black pixels are logically included in the resultant region 
whereas 

; white pixels are not included. 
required 

; of the bitmap - it may be arbitrarily complex. 
will 

; simply yield an empty region. rgnBBox of resultant rgn may 


No special conditions 


Empty bitmap 


; be smaller than initial bitmap bounds if image does not use 
; full extent of the bitmap. rgnBBox will be smallest rect 
; enclosing the resultant region. 

f Algorithm Summary: 


7 

2 

; The idea behind the conversion is simple. The key is in 

f inding 

; inversion points of the picture which define the region. A 
; source bitmap is first XOR’d with its right-shifted copy. 

; resultant bitmap is then XOR’d with its down-shifted copy. 
; produces a set of inversion points which define the region 
; boundary. next step is to take these points within final 
J 

; 

; 

; 

; 

д 

; 


: bitmap and convert them to Quickdraw region format. 
FUNCTION MakeRgn(srcMap: Bitmap): RgnHandle; 
Modification History: 


25 Mar 87 New Today. 
‚ 26 Mar 87 Ironed out those bugs! 
30 Mar 87 Changed to a Pascal function. 


28 Mar 88 Optimized and reduced code. 


rE 


MACHINE MC68000 


INCLUDE 
INCLUDE 


‘Traps .a’ 
‘QuickEqu.a’ 
ENDMARK EQU $7FFF ; end of rgn/line mark [word]. 


; MakeRgn’s stack frame: 


MRFrame RECORD (A6Link),DECR 
dstRgn DS.L1 ; output region [RgnHandle]. 
srcMap DS.L1  ; source bitmap [Ptr]. 
Return DS.L1  ; return address [Ptr]. 
A6L ink DS.L1 ; old A6 value [long]. 
srcRect 05.88 ; temporary [Rect]. 
dstRect 05.88 ; temporary [Rect]. 
rgnMap DS.B 14 ; temp bitmap [BitMap]. 
VarSize EQU * ; size of local variables. 
ENDR 
MakeRgn PROC EXPORT 
WITH MRFrame 
LINK A6,#VarSize; create local stack frame. 
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we We We `. 


wee We We `. 


MOVEM.L 
MOVE.L 
MOVEQ 
MOVEQ 
MOVE .W 


Find number of lines in source bitmap. 


À1-A3/D0-D7 , -CSP) 
SrcMap(CA6), АЗ 

80 DO ; clear for multiplying. 

80 D4 ; use D4 for faster clears. 
rowBytes(A3),D7 ; load srcMap rowBytes. 


; Save working registers. 
; load ptr to source bitmap. 


The rgnMap will have 


the same number of lines plus one and two more rowbytes. 


MOVE .W 
SUB . W 
ADDQ.W 
ADDQ.W 


Fill in rgnMap rowButes and baseAddr fields. 


bounds+bottom(A3),D8 ; load srcMap bottom. 
bounds+top(A3), DØ ; height = bottom-top. 
81/00 ; height++. 

82/07 ; rowButes += 2, 


Allocate 


memory for the temporary rgnMap image buffer. 


MOVE .W D7,rgnMaptrowBytes(A6); store new rowBytes. 

MULU 07,00 ; calculate bitmap size. 

-NewPtr ,clear ; create rgnMap image buffer. 

MOVE.L A®,rgnMaptbaseAddr(A6); store start of buffer. 
; rgnMap's bounds will be one pixel larger to the right and 
bottom. 

MOVE.L bounds+topLeftCA3),D8 ; get original bitmap bounds. 

MOVE.L — bounds*botRight(A3)2,D1 

ADDQ.W 8101 ; right**. 

MOVE.L — DO,rgnMap*bounds*topLef t (A6) 

MOVE.L D1,rgnMap+bounds+botRight(A6) 

ADDQ.W — *1,rgnMap*bounds*bottom(A6) 
; Now make right-shifted copy іп rgnMap. 

ADDQ.W 81/00 ; leftt+. 

MOVE.L — DO,dstRect*topLeft(A62; dstRect is right-shif ted 
one. 

MOVE.L  Di,dstRect*botRight(A6) 

MOVE.L — A3,-CSP) ; srcBits = srcMap. 

PEA rgnMap(A6) ; dstBits = rgnMap. 

PEA bounds(A3) ; srcRect = srcMap.bounds. 

PEA dstRect(A6); dstRect. 

MOVE.W D4,-(SP) ; srcCopy mode. 

MOVE.L 04,-С5Р) ; no maskRgn. 

-CopyBits 


`. 


` . 


`. We 


XOR srcMap with right-shifted copy rgnMap & store in rgnMap. 


MOVE.L A3,-(SP) ; srcBits = srcMep. 

PEA rgnMap(A6) ; dstBits = rgnMap 

PEA bounds(A3) ; srcRect = srcMap.bounds. 
PEA boundsCA3) ; dstRect = srcMap.bounds. 
MOVE.W — "'srcXor,-CSP) ; SrcXor mode. 
MOVE.L — D4,-CSP) ; no maskRgn. 

-CopyB its 


XOR rgnMap with down-shifted copy of rgnMap. 


MOVE.L — rgnMaep*bounds*topLef t(A6), srcRect*topLef t (A6) 
MOVE.L rgnMap+bounds+botRight(A6),srcRect+botRight(A6) 
MOVE.L srcRect+topLeft(A6),dstRect+topLeft(A6) 
MOVE.L srcRect+botRight(A6),dstRect+botRight(A6) 
SUBQ.W #1, srcRect+bottom(A6) 

ADDQ.W  "1,dstRect*top(CA6) 

PEA rgnMap(A6) ; srcBits = rgnMap. 

PEA rgnMap(A6) ; dstBits = rgnMap. 

PEA srcRect(A6); srcRect = top rectangle. 

PEA dstRect(A6); dstRect = down-shift one. 

MOVE.W ¥srcXor,-CSP) ; SrcCopy mode. 

MOVE.L 0D4,-(SP) ; no maskRgn. 

_СоруВ i ts 


We've exposed the inversion points of the picture. 


Time to 


count the number of rows and black pixels in the rgnMap to 


14 


determine 


; the size of the RgnHandle we will soon fill in. 


MOVE.L 
LSR.W 

SUBQ.W 
MOVE.W 
MOVE.W 


rgnMap+baseAddr(A6),A0; start at topLeft of bitmap. 
81/07 ; rowWords = rowBytes/2. 

81,07 ; loop rowWords times. 
rgnMap+bounds+top(A6),D1; current Y coordinate. 
rgnMap+bounds+bottom(A6),A1 


; last Y coord. for end test. 


MOVEQ 
Count 
MOVE .W 
MOVEQ 
eo 
MOVE .W 
BEQ.S 
TST.B 
BNE.S 
STD3 
ADDQ | 
61 
ADDQ.W 
MOVE.W 
SUBQ.W 
AND.W 
BNE .5 
62 
DBRA 
ADDQ.W 
CMP.W 
BGT.S 


`. 


TST.W 
BNE.S 
SUBQ.W 
-NewRgn 
MOVE.L 
BRA 
BuildRgn 


Calculate number of 


handle. 
MOVEQ 
ADD .W 
ADD | 
ADD | 
ADD .W 
ADD .W 
MOVE.W 


-NewHandle ,clear ; 


MOVE.L 


7 


#0,D5 ; row count = 0. 
07,06 ; x loop on rowWords. 
80 03 ; Clear line flag. 


(A0)+,D0 ; load next rgnMap word. 
02; skip blank words. 

D3; is line flag alreadu set? 
01; yes — skip. 

‚ nO — set line flag. 


81,05 ; row countt+. 

81,04 ; 8dd number of bits 

00,02 ; іп rgnMap word to 

81/02 ; total bit count. 

02,00 

01 

06,00 ; loop if more words to read. 
81,01 ; ytt. 

D1,A1 ; у €= bottom? 

Count ; yes — loop. 


Determine size of new RgnHandle. 


D5; was the rgnMap empty? 
BuildRgn ; no — skip. 


84,50: ; yes — get new empty region. 
(SP )+, dstRgn(A6 ) ; stuff result. 
Done ; exit. 


bytes to allocate for output region 


812,00 ; (12 for header & end mark.) 
D1,D1 ; C4*number of lines in map for 
D1,D1 , each Y coordinate and 

01,00 ; end mark.) 

D4,D4 ; X2*number of inversion 

D4,D0 ; points in the entire map.) 
00,04 ; remember the region size. 


allocate a cleared RgnHandle. 
A@,dstRgn(A6) ; Store handle in result. 


Translate rgnMap (containing inversion points) into Quick- 


draw Region 


; format. We do not need to lock block because we will be 


making no 


; trap calls which might rearrange the heap. DstRect will be 


used to 


; help us find smallest enclosing rectangle for the region. 
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MOVE.L 
MOVE.W 
MOVE.L 
LEA 

MOVE.L 
MOVE.W 
MOVE.W 
MOVE.W 
MOVE.L 


CAO), AO ; point to гоп data. 

D4,rgnSize(A0) ; Store region size. 

А0,А2 , Save ptr for the end. 

rgnData(A0),A0 ; Offset ptr to rgnData. 
rgnMap+baseAddr(A6),A1; point to topLeft of bitmap. 
rgnMap+bounds+top(A6),D1; u = top. 
D1,dstRect+bottom(A6) ; initialize dstRect... 
rgnMap+bounds+lef t(A6),dstRect+right(A6) 
rgnMap+bounds+botRight(A6), dstRect+topLef t(A6) 


The line flag tells us if the scanline is not completely 
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blank after 
; reading whole line. If not blank, we add end-of-line mark. 
Translate 

MOVE.W D7,D6 ; load word count. 

MOVEQ 80,05 ; clear line flag. 


MOVE.W rgnMap+bounds+lef tCA6),D3 
; x = left edge. 
60 
MOVE.W CA1)+,D8 ; load srcMap word. 


BNE.S @NotEmptu ; only process non-zero words. 

ADD.W 816,03  ; skip zero words for speed. 

BRA.S 684 
@NotEmptu 

TST.B D5; is line flag set? 

BNE.S 61; yes — skip. 

STD5 ; no — set line flag. 

MOVE.W D1,CA0)+ ; store y coord. in structure. 

CMP .W dstRectttopCA6),D1 ; now find the topmost 

BGE.S @MaxBottom ; row of the region. 

MOVE.W ) Di,dstRect*topCA6) ; top = minCtop,y). 
eMaxBottom 

CMP.W — dstRect+bottom(A6),D1 ; now find the bottommost 

BLE.S 61: row of the region. 

MOVE.W  Di,dstRect*bottom(A6) ; bottom = max(bottom,y). 
e1 

OR#$10,CCR ; set the X flag. 

ADOX.W 00,00 ; Shift in end-bit-marker. 
82 

BCC.S 63; branch if MSB clear. 

MOVE.W D3,CA®)+ ; store x coord. in structure. 

CMP .W dstRect+left(A6),D3 ; now find the leftmost 

BGE.S eMaxRight ; edge of the region. 

MOVE.W  D3,dstRect*left(A6) ; left = minCleft,x). 
@MaxRight 

CMP .W dstRect+right(A6),D3 ; now find the rightmost 

BLE.S ӨЗ; edge of the region. 

MOVE.W  D3,dstRect*right(A6) ; right = maxCright,x). 
63 

ADDQ.W 81,03 ; increment the x coordinate. 

ADD .W 00,00 ; shift msb bit into carry. 

BNE.S 62; repeat if more one-bits. 
84 

DBRA 06,80 ; loop оп rowWords-1. 

TST.B D5; emptu line? 

BEQ.S 65. yes — 

MOVE.W 
65 

ADDQ.W #1,D1 ; increment the y coordinate. 

CMP .W rgnMap*bounds*bottomCA62,D1 
; loop if y <= bottom rgnMap. 

BLT.S Translate 


Mark the end of the region and fill in the rgnBBox field. 


we We We We 


MOVE.W — "ENDMARK, CAS) ; store end-of-region mark. 
MOVE.L  dstRectttopLeft(A6),rgnBBox+ttopLef tCA2) 
MOVE.L dstRect+botRight(A6), rgnBBoxtbotRightCA2) 
Done 
MOVE.L  rgnMap*baseAddr(A6),A0; deallocate temporary 
bitmap. 
_DisposPtr 


MOVEM.L (SP)+,A1-A3/D8-D7 ; restore working registers. 
UNLK A6; unlink the stack frame. 


MOVE.L (SP)+,A@ ; load return address. 
ADDQ 84 SP ; pop parameter. 
JMP (A0); return. 
ENDWITH 
ENDPROC 
END 
Listing 2. Pict2Rgn. 
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ЧЕМОМАКК, CA22* ; no, Store end-of-line mark. 


We are finished entering information into the rgnData field. 


/*<——— — nD o nv 
NAME 
Pict2Rgn - convert PICT resources to Quickdraw region 
format. 
SYNOPSIS 
Pict2Rgn [file] [-v] 


files any resource file containing PICT resources 

-v= verbose flag 
DESCRIPTION 

Converts PICT resources within a file to Quickdraw 

region format. ID’s of the generated regions will be the 

same as the source PICT’s. region resource type is ‘RGN '. 

Does not check to see if RGN resources are already there. 
AUTHOR 

Written Ted Cohn, March 1988. 

Copyright Ted Cohn, 1988. 

/ 


include «types.h? 
include «stdio.h? 
include «resources.h? 
include <quickdraw.h> 
include «memory.h? 


define RgnType ‘RGN ' 


pascal RgnHandle MakeRgn(srcMap ) 
BitMap *srcMap; 
extern; 


mainCargc, argv) 
int argc, 
char *argv[]; 


Rect frame; /* picture frame */ 

GrafPort gp; /* offscreen GrafPort pictures are drawn */ 
short index; /* for-loop variable */ 

short refNum; /* the resource file’s refNum */ 

short pictCount; 

/* number of picts in resource file to convert */ 

Handle pictHandle; /* handle to current picture */ 

short rowWords; /* #of words across picture’s bitmap */ 
BitMap srcMap; /* GrafPort’s bitmap */ 

short theID; /* resource ID from GetResInfo */ 

ResType theType; /* resource TYPE from GetResInfo х/ 
RgnHandle theRgn; /* hdle region converted from picture */ 
Str255  theName; /* resource NAME from GetResInfo */ 

short verbose; /* boolean signals to print more info */ 


verbose = (агдс›2); /*boolean more than 2 arguments given */ 


/* Must initialize Quickdraw for the conversion process */ 
InitGraf C&qd. thePort); 
/* if no argument supplied, then print info about tool х/ 
printf(“Vn”); 
if (argc<2) ( 
fprintf(stderr, *\nUsage: Pict2Rgn «resource file>”); 
fprintf(stderr, ”\n -Converts 811 PICT resources to 
Quickdraw region format."); 
fprintf(stderr,”\n -ResType is ‘RGN ', ID’s correspond to 
PICT ID’s.”); 
fprintf(stderr, "An -Written by Ted Cohn, March, 
1988.\п”), 


exit(1); 
) 
/* Trg to open resource. If errors, report and exit. */ 
if ((refNum = OpenResFile(argv[1])) == -1) ( 
fprintf(stderr, “\nCan’t open the resource file 55 .\п“, 
argv[1)); 


exitCD; 
) 
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/* Find out how manu to convert. Exit if no picts in file.*/ 
if ((pictCount = Count IResources(‘PICT’)) == Ø) ( 


fprintf(stderr, “\nThere are no PICTs in this file to 


convert.in^); 


CloseResF i leCref Num); 
exit(1); 


if (verbose) 

fprintf(stderr, “PICT Count = %dVn”, pictCount); 
/* Now convert each PICT to RGN format */ 
for (index = 1; index <= pictCount; іпдех++) ( 


/* Get a picture and lock it down */ 
HLock(pictHandle = Get iIndResource( ‘PICT’, index )); 
/* Must get the picture’s ID */ 
GetResInfoCpictHandle, &theID, &theType, &theName); 
/* Get the picture’s frame rectangle */ 

frame = *((Rect *) (*pictHandle + 2)); 

/* Calculate size of srcMap we need to allocate */ 
rowWords = (frame.right-frame. left-1)/16+1; 
srcMap.baseAddr = NewPtr(Clong) (Cframe.bottom- 


frame. top )*rowWords*2)); 


srcMap.rowBytes = rowWords*2; 
srcMap.bounds = frame; 


/* Open offscreen GrafPort and set bitmap to our srcMap */ 


OpenPort(&gp); 

Se tPor tBi ts(&srcMap); 
RectRgn(gp.clipRgn, &frame); 
RectRgn(gp.visRgn, &frame); 
gp.portRect = frame; 
DrawPicture((PicHandle) pictHandle, &frame); 

ClosePor t(&gp); 

/* Now convert the picture from a srcMap to a region */ 
theRgn = MakeRgn(&srcMap); 
Re leaseResource(pictHandle); 


DisposPtr(srcMap .baseAddr ); 
if (verbose) 

fprintf(stderr, “Converted (%d) PICT ID = йл”, index, 
іһе10); 


/* Add the new region to the file апа dispose of it */ 
AddResource(theRgn, RgnTupe, theID, &theName); 
WriteResource(theRgn); 
ReleaseResource(theRgn); 


/* All done, so close the resource file */ 
CloseResF ile(refNum); 
exit(0); 

) 


Listing 3. Make file for Pict2Rgn. 


File: Pict2Rgn.make 

Target: Pict2Rgn 

Sources: MakeRgn.a Pict2Rgn.c 

Created: Sundau, April 3, 1988 11:25:18 AM 


MakeRgn.a.o f Pict2Rgn.make MakeRgn.a 
Asm MakeRgn.a 
Pict2Rgn.c.o f Pict2Rgn.make Pict2Rgn.c 
C Pict2Rgn.c 
Pict2Rgn ff Pict2Rgn.make MakeRgn.a.o Pict2Rgn.c.o 
Link -t MPST -c ‘MPS 79 
* (CLibraries)^CRuntime.o à 
* (CLibraries)"StdCLib.o 9 
“(CLibraries)}*CSANELib.o à 
* (CLibraries)^CInterface.o д 
MakeRgn.a.o à 
Pict2Rgn.c.o à 
-0 Pict2Rgn 


€ The Best of MacTutor, Vol. 5 


Developer Notes 
MDS->MPW 


Converting MDS files to MPW 


This article describes how to convert MDS assembler source 
files to the MPW environment. I don’t go into all the details, but 
try and give you enough of the major points so that you can get 
your old files over to MPW and get more productive. MPW isa 
very rich and wonderful environment and I am purposely ignor- 
ing many of its subtle and not-so-subtle features in this article for 
the sake of clarity (and deadline). 


Declare a MAIN Procedure 
MPW expects you to declare at least one code module in 
your source file. There are several ways to start a code module, 
but the easiest is to put the MAIN directive on the same line at the 
label at the start of your code producing statements. Forexample, 
the following code fragment establishes the label “Start” and the 
main code module. 


Start MAIN ; code statements start here 


If you don’t declare a code module, either by using MAIN or 
PROC or FUNC, MPW will complain heartily. 


Declare Global Data Record 

In MDS, it is customary to declare global variables with the 
DS directive. The MDS assembler gathers all DS directives 
together into a common global data block and tells the linker to 
locate the data block at -256(a5) when the program is loaded. 
(This location is the default and you can change it with Link 
directives, although most people don’t bother to change it. Later 
in this article when we discuss the QuickDraw globals, you will 
see that the location of the application globals in MDS is 
important.) All the labels associated with the DS statements 
become negative offsets from А5 to the proper location in the 
dataarea. For example, if you have the following data statements 
in your MDS file: 


thePoint ds.1 1 
theRect ds.w 4 


¿space for a Point 
;4 words for a Rect 


You can access those variables by using the name of the 
variable as an offset from register a5, as in this line of code. 


move. | thePoint(a5),-Csp) 


In MDS files, DS directives can be placed anywhere in the 
file, and the assembler will gather them all together and make a 
single data block. The MPW assembler also gathers up DS 
statements and makes code modules and the MPW linker com- 
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bines all the data modules and place them just below the a5 
boundary points when the program is loaded. The MPW linker 
does not give you an automatic 256 byte cushion below the a5 
boundary the way the MDS linker does. Labels for DS state- 
ments become negative offsets from register a5, however, in 
much the same way as in MDS. You can access MPW assembler 
data variables by using the variable name (label) as as offset from 
register a5, as shown in the previous example. 

A better way to declare global variables in MPW is to gather 
all your DS statements together into a RECORD and then use that 
data template to access all your globals as fields of the template. 
For example, to convert the global variables from the MDS 
example above, you would place the following data declaration 
at the beginning of your file (after the ‘INCLUDES’ and 'EQU' 
statements but before the first code statements). 


MyData RECORD 

thePoint ds. 1 1 

theRect ds.w 4 
ENDR 


Once you declare a block of globals this way, you can access 
the individual variables without referencing register a5, since the 
MPW assembler will automatically generate the ar reference for 
you. You access a variable by using its data module name ( eg. 
‘MyData’) and a field name from the data template (eg. 
‘thePoint’), much like a record structure in C or Pascal. For 
example, you can access the variable at the label *thePoint" with 
the following code. 


томе.1  MygData.thePoint,-Csp) 


You can also declare implicit data modules by using the 
WITH directive. For example, if you preceded the previous 
example with the statement: 


Start MAIN 
WITH MyData 


; Code statements begin here 


you could dispense with the data module name when access- 
ing individual fields of the data module, so that the access 
statement becomes: 


move.]  thePoint,-Csp) | 
In summary then; when converting an MDS file to MPW, 


gather all your DS directive lines into a single data module and 
give the data module name (the label that appears on the same line 
as the RECORD directive) ina WITH statement before accessing 
any of the variables in the data module. You can then access the 
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variables by using their names without worrying aboutreferenc- 
ing register a5. 


Declare QuickDraw Globals 

One of the hidden features of the MDS linker is that it places 
the application globals 256 bytes below the a5 boundary by 
default. The MPW linker places the application globals right 
below the a5 boundary, without any cushion. Most casual assem- 
bly language programmers (is there such a thing?) just accept the 
default and don’t really think about it, but it can get you in a lot 
of trouble when converting between MDS and MPW if you don’t 
take this difference into account. 

In particular, itiscommon for MDS programs to assume that 
the QuickDraw globals will be placed just below the a5 bound- 
ary, extending downward in memory for 206 bytes. The ROM 
call InitGraf expects a pointer to the 203rd byte of a 206 byte area 
for the QuickDraw globals. Because MDS gives a 256 byte 
cushion below the a5 boundary before the application’s globals, 
MDS programs typically call InitGraf with a pointer to a long 
word four bytes below the a5 boundary, as shown below. 


; typical MDS technique 
pea -4(а5) 


_InitGraf 


This works great in MDS programs because the QuickDraw 
globals grow downward from the a5 boundary but are not large 
enough to outgrow the 256 byte cushion provided by the MDS 
linker, 

In MPW, you are not so lucky. You must explicitly allocate 
some global storage for the Quickdraw globals in a data module 
and then pass a pointer to that module when calling InitGraf. If 
you don’t do this and use the previous code to initialize Quick- 
Draw, your globals and the QuickDraw globals will share over- 
lapping data space beneath the a5 boundary, and that will cause 
your program to crash as your program and QuickDraw write 
over each others globals. 

The sample program provided with MPW shows a good 
method for allocating data space for the QuickDraw globals. 
Listed below is a simplified version of that method. First, declare 
a data module for the QD globals. This declaration should come 
just before or just after your application’s data declaration, but 
before any code statements, as shown below. 


QDGlobals RECORD ,DECREMENT 


thePor t ; 1 
white 05.8 8 
black DS.B 8 
gr'au DS.B 8 
1tGrau DS.B 8 
dkGray DS.B 8 
arrow DS.B cursRec 
screenBits DS.B bitmapRec 
randSeed DS.L 1 
ORG -grafSize 


ENDR 


Once the QD globals data module is declared, it will be 
combined with any other data modules in your program and 
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loaded just below the a5 boundary when the program is loaded. 
Because you don't know exactly where the QD globals will be 
loaded in relation to the other data modules (alright, if you dig 
through the MPW manuals you can probably figure out how the 
data modules are ordered). 

In order to use the QuickDraw globals that are defined as a 
data module, you should place the name of the data module in the 
WITH directive along with the name of your application's data 
module, as shown below. 


Stert MAIN 
WITH MyData, QDGlobals 


; Code statements begin here 


And, once you are using the QD globals you have defined, 
you can point directly to the QD data area when initializing 
QuickDraw, as shown below. 


; thePort is a variable in QDGlobals 
pea thePor t 


-InitGraf 


By explicitly defining a data area for the QuickDraw globals 
and pointing toit when initializing QuickDraw you can avoid the 
data overlap that occurs when you convert an MDS program 
without thinking about the details. 


Misc Details 
— MPW uses IMPORT and EXPORT instead of the XDEF 
and XREF directives found in MDS. 
— Macros are defined differently in MPW and MDS. For 
example, take a look at the following macro defined for both 
MDS and MPW: 


MDS macro: 


MACRO _SFGetFile = 
MOVE.W #2,-C(SP) 


-Pack3 
| 


MPW equivalent macro: 


MACRO 

—SFGetFile 
MOVE.W #2,-(SP) 
-Pack3 


ENDM 


— The labels used with EQU and SET statements in MPW 
must be in the first column, unlike MDS. 

— RMaker and rez source files are totally incompatable, but 
you use your old resource files by either including" them in your 
rez file or running derez on them to get a rez compatable source 
file. 

— Make files made by the “Create Build Commands...” 
menu option in MPW typically are a good way to build your 
programs, but you can remove the link files "Runtime.o" and 
"Interface.o" put in the make file by default. J 


Sol 


A 
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Assembly Lab 
Cerial (Serial) I/O 


Programming The Serial Ports 

The Macintosh serial ports are a neglected programming 
subject. Few (if any) books on programming cover them, and this 
lack of information is compounded by an absence of source code 
to study. 

The simplest way of programming the serial ports is to use 
a high level language and fool the compiler into thinking that the 
ports are disk files. Then you can use the language’s generic file 
I/O routines for serial I/O. While this solution provides a simple 
way of dealing with the serial ports, it may not provide the speed 
or flexibility that may be required in certain applications. 

I thought that a better approach would be to write a set of low 
levelroutines thatcan be linked with compiler generated code, or 
with assembly language. How difficult could this be? All I'd 
need was the hardware manual for the Mac’s serial port chip, a 
copy of Inside Macintosh, a steady source of caffeine and a few 
hours of coding...right? 

I quickly discovered that the task of writing drivers for the 
Mac is serious business. Life is too short for the hassles involved 
in trying to write a driver for the the complex (and bizarre) serial 
port chip, a Zilog 8530 SCC. Besides, it's already been done; 
Kirk Austin's excellent articles “A Midi Library for Pascal" and 
“Midi Demo Uses Midi Library” in the July, 1987 and December, 
1987 issues of MacTutor show how to write drivers for this chip, 
if you’re interested in working close to the bare metal of the 
machine. 


How | Learned To Stop Complaining And Love 
The Device Manager 
or 
“Gee, | didn’t realize it would be this easy” 

Midi has certain timing and handshaking constraints that 
demand specialized serial drivers. I needed something a lot 
simpler; a set of routines that could send and receive data, at baud 
rates that would probably never exceed 19200 kilobaud. There 
had to be a way of doing this thatdidn’t involve writing acomplex 
driver. As often happens when programming the Macintosh, a 
solution became obvious only after re-reading several chapters of 
Inside Macintosh (or to put it another way: “when all else fails, 
read the manual”). While the Serial Drivers chapter would seem 
like the obvious place to look for information on using the serial 
ports, the Device Manager chapter is far more important; the 
Macintosh treats the serial ports as devices, so accessing the 
drivers requires using the Device Manager I/O routines. 

The Device Manager can be divided into Pascal based file I/ 
O routines, and low level traps. The high level Pascal routines 
(they can also be called from C. But you already knew that) have 
an extremely simple calling sequence, and insulate the program- 
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mer from the inner workings of the Device Manager. However, 
since these routines are not in the ROMS, the glue routines have 
to be linked with any assembly language program that uses them. 

The low level Device Manager traps require more work to 
use, but they provide greater control over the I/O. I could have 
used the high level routines in my program, but since I had to use 
a low level Device Manager trap to configure the serial port, I 
decided to write everything using the other low level traps; the 
code is smaller and probably a bit faster. 

The serial ports have been assigned four driver reference 
numbers, which are used by the Device Manager to identify the 
device it is working with: 


Modem port input C port A) -6 
Modem port output C port A) -7 
Printer port input C port B5) -8 
Printer port output C port B2) -9 


I've used these reference numbers directly in the code, 
instead of using the reference numbers returned by the Open 
trap (the numbers should be the same). It simplifies the coding, 
at the risk of making the routines non-functional if and when 
Apple decides to change the reference numbers. 

The Device Manager traps use a block of memory (pointed 
atby register AO) called a parameter block. Itholds the pointers, 
commands and flags that may be required by the Device Manager 
trap being called. Depending on the call, it may also contain 
information returned from a device. A generc parameter block 
can be up to 80 bytes long, but when calling the serial ports most 
of the parameter block entries can be ignored. This still means 
that my routines have to set up and maintain a parameter block 
each time they are called. At first, even this small overhead in 
execution time and memory requirements made me uncomfort- 
able; however this is an acceptable compromise considering the 
amount of code required to write a low level serial driver. 

Inretrospect, using the Device Manager to control the serial 
ports turned out to be an easy task, although I spent more time 
than I'm willing to admit learning how to write these serial I/O 
routines. In the process, I discovered that Apple provides serial 
port drivers in a resource called SERD (built into the ROMsof the 
more recent Macs). At the time I wrote my routines, SERD was 
not in ROM and its use was (and still is) poorly documented. It 
was also more code than I had expected, so I went ahead with my 
routines. 

One of my first attempts at using the Device Manager was a 
simple terminal program written in Turbo Pascal. It worked, but 
I decided to re-write it in assembly because (I know many of you 
will cringe) I enjoy writing in assembly language! I realize that 
it’s an acquired taste and that most of you would prefer to keep 
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your contacts with assembly language to a minimum, so these 
routines have been written to make them accessible from Pascal. 
The routines will also work with C, but you may have to modify 
them to match the C parameter passing protocol. I’ve also written 
asmall terminal program that shows the routines in use. The bulk 
of the program consists of code to use TextEdit, manipulate the 
clipboard and code to do the usual housekeeping routines. You'll 
almost need a magnifying glass to find the calls to the serial 
routines! 


Serial /О Routines 

The serial I/O routines make extensive use of the stack, for 
parameter passing and for holding the parameter block required 
by the Device Manager routines they'll be calling. 

Parameter blocks are common structures, and can be found 
in most Macintosh I/O routines. In assembly language, we can 
define a parameter block as a buffer in the global variable space, 
or we can use the approach used by many high level language 
compilers and define the parameter block as a temporary struc- 
ture on the stack. On entry, each routine sets aside a small section 
of the stack, known as a stack frame, and points to it with register 
A6. This private section of memory is then set aside as a 
parameter block. 

Making the parameter block a temporary structure on the 
stack saves us from having to declare it as part of the global 
variable space; the local stack frame and all its contents are 
discarded when the routine terminates. Using this technique 
increases the complexity of the routines, but their portability and 
ease of use far outweighs the minor increase in execution time 
and code size. 

Before we use a serial port, its driver must be open and the 
port must be configured. OpenSerial opens the specified serial 
port driver (either the modem or the printer port) and kills any 
pending I/O operations to it. The routine uses the driver’s input 
reference number (-6 for the modem port and -8 for the printer 
port) to open both the input and output sections, and expects to 
find the appropriate number on the stack. Figure 1 shows the 
local stack for the OpenSerial routine. 

OpenSerial starts by setting up the stack frame and allocat- 


OpenPort 


10(A6) в» wore 


(А6) —> word 


long 


4(A6) —» d A6 
Save 
(Аб) — ong 
Parameter 
block 
(sp) —> «4— -pBlock(a6) 


Figure 1 Local stack for OpenSerial 
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ing the space for the parameter block. It then makes register AO 


point to the parameter block, as expected by the Device Manager. 


OpenSerial uses the Device Manager _Open trap which at most 
has only three entries in it’s parameter block. Since none of 
these serial I/O routines are making asynchronous calls to the 
Device Manager, OpenSerial can ignore the ioCompletion 
pointer. It can also ignore the ioPermssn byte, leaving only 
ioNamePtr, which is filled after OpenSerial checks which port is 
to be opened. Since both the input and output sides of a port must 
be opened, OpenSerial calls the Device Manager Open trap 
twice. Once this is done, the routine saves the result code 
(returned in the parameter block at ioResult) on the return stack 
and calls the Device Manager one more time, to kill any pending 
I/O operations to the port. Since the parameter block remains 
unchanged, OpenSerial can call the KillIO trap directly. Before 
returning to the calling program, OpenSerial discards the local 
stack (and the parameter block) and clears the port number from 
the return stack, leaving only the result word. 

The code segment below shows the calling sequence for 
OpenSerial (PortA refers to the modem port driver and was set to 
-6 by an equate statement somewhere else in the program). 


clr.w -(sp) ; room for result 
move.w #PortA,-(sp) ; modem port 

jsr OpenSer ial 

tst.w (sp) ; leave result on stack 
bne Abort 


Since OpenSerial is usually followed by the configuration 
routine, I leave the result code on the stack (it will be zero if the 
port opened successfully) and use it to mark the space for the the 
next routine’s result code. Config resets the serial port and sets 
it to the new baud rate, data bits, stop bits and parity desired. 
Config doesn’t modify some of the other important serial port 
parameters (mainly handshaking) since the default parameters 
suited my needs. Like OpenSerial, Config expects to see the 
port’s input driver reference number on the stack. It also expects 
to see a configuration word, which represents the baud rate, data 
bits, stop bits and parity being set. Figure 2 shows the local stack 


f word 
12(A6) -> ConfRes 
10(А6) а ConfPort word 
8(А6 —- 
4(A6) в return LL long 
saved A6 
(А6) -> long 
Parameter 
block 
(sp —» <6-- -pBlock(a6) 


Figure 2 Local stack for Config 
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for Config and the code section below shows its calling sequence. 


move.w *PortA,-Csp) ; modem port 
move.w "Conf ig 1200,-С5р) 


jsr Conf ig 
tst.w (sp) ; leave result on stack 
bne Abort 


Config uses the Device Manager . Control trap, which 
requires a few more parameters than OpenSerial. Two parame- 
ters, ioCompletion and ioVRefNum (serial ports don't have 
volume names) can be ignored, but it must set the ioRefNum to 
that of the port being configured. Config uses the csCode 
parameter to tell the Device Manager to reset the port. The new 
configuration value is passed in csParam. 

For some applications, opening and configuring the serial 
portis all you need to do to initialize it for use. Unfortunately, the 
default size of input driver's buffer (set by the Device Manager) 
is a tiny 64 bytes, and this small buffer can become a major 
problem. 

We all know that TextEdit is no speed demon. If you're 
writing a communications program and use TextEdit to display 
the incoming text, characters may be received by the port faster 
than TextEdit can display them. The 64 byte serial input buffer 
will quickly overflow and you will lose some characters. Luck- 
ily, this input buffer can be resized using SetBuf. This routine, 
like OpenSerial and Config, requires a reference number for the 
port's input driver. Italso requires a long word that represents the 
buffer's new size. 

SetBuf, like all the other routines, starts by setting aside 
some room for the parameter block. It will then request a 
nonrelocatable block from the Memory Manager to serve as the 
new input buffer. If SetBuf succeeds in getting the new block, it 
tells the input driver to use this buffer through the Device 
Manager . Control trap. Figure 3 shows the local stack for 
SetBuf. 


move.w "PortA,-(sp) ; modem port 


SetPort 


word 


14(A6) —Ъ 
word 


12(А6) —»- 6 
etSiz 
slas) p| S7 [on 
sac) e tum airs fon 
saved A6 
(Аб) -»- ы long 
Parameter 
block 
(sp) -» <4- -pBlock(a6) 


Figure3 Local stack for SetBuf 
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move.] #512,-(sp) ; 512 byte buffer 
jsr Se tBuf 

move.w (sp)+,d@ ; take result off stack 
bne Abort 


In this example, the input buffer is made 512 bytes long. 
Since SetBuf is usually the last step in initializing a serial port, the 
result word that was floating on the stack from the previous two 
routines (OpenSerial and Config) finally gets popped off. As 
we've come to expect, if SetBuf has a problem allocating the 
memory for the buffer, this word will be non-zero. 

It’s important to set the input buffer back to the default value 
before terminating your program (the programmer’s motto 
should be “always leave things the way you found them”). This 
can be done with SetBuf by passing a value of 0 as the size of the 
buffer. The Device Manager will then set the input buffer back 
to its default value. 

Once the serial port has been opened and initialized and the 
size of the serial input buffer has been increased, your program 
is ready to send and receive data through the port. 

The input routine GetSerial takes two parameters, the port 
number and a pointer to the buffer that will hold the incoming 
data (note that this isn’t the same as the input driver buffer). 
GetSerial first checks to see if there are any characters waiting to 
be read by calling SerGetBuf, which is a special version of the 
Device Manager _Status trap. This Device Manager call returns 
a long word containing the number of characters in the driver’s 
input buffer. If the input buffer is empty, GetSerial will leave this 
zero count on the stack and end. If there are characters available 
(and if you use TextEdit, there will be quite a few backed up), 
GetSerial reads them into the new buffer using the Device 
Manager _Read trap. GetSerial then leaves the character count 
on the stack and ends. Figure 4 shows the local stack for 
GetSerial. Here’s an example from the terminal program: 


clr.1 -(sp) 
move.w #PortA,-(sp) 
pea IOBuf Ca5) 
bsr GetSer ial 


GetCnt 
GetPort 


; room for char count 
; use the modem port 
; put data here 


long 
14(А6) —- 


12(А6) -»- 
8(A6) —» 
4(A6) —» 

(А6) —» 


мога 
long 
long 


long 


Parameter 
block 


(sp) -» <4- -pBlock(a6) 
Figure4 Local stack for GetSerial 
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move.] (sp)+,CharCnt(a5) ; save count 


PutSerial simply shoves data out the port, letting the Device 
Manager worry about errors (like overflowing the output buffer). 
Since we are calling PutSerial synchronously, this is not a serious 
shortcoming and PutSerial will work well, without problems. 

PutSerial takes three parameters, the port number, a pointer 
to the buffer holding the data to be sent and the number of 
characters to be sent. Even though PutSerial ignores errors, it 
returns a “по errors" result value to the calling program; this is to 
keep it consistent with the other routines and to make room for a 
real error value if a future version of the routine does check for 


settings. It also uses the clipboard, so you can cut and paste text 
to and from its window. While the text that is pasted to the 
terminal window is displayed, it is not sent out the port (as my old 
calculus book would say “Ше solution to this problem is leftto the 
reader”). The main window in Term is moveable, but not 
resizable. This is a minor annoyance, which can be easily fixed. 

Term will run on almost any Macintosh (it doesn’t run on 
Macs with the old 64K ROMs) and is structured to serve as the 
skeleton of a more complex communications program. To 
maximize speed and reduce the need for global variable storage, 
most assembly language programmers store frequently used 


errors. The calling sequence is pretty simple: 


clr.w 8g,-(sp) 
move.w ""PortA,-Csp) 
pea IOBufCa5) 
pea CharCntCa5) 
bsr PutSerial 


room for dummy 
modem port 

send data in buffer 
this many 


; 
; 
; 
; 


move.w (sp)+,d8 ; pop dummy 


Figure 5 shows the local stack for PutSerial. 


PutRes word 


18(A6 — > 
16(А6) — 


PutPort word 
PutBuf long 
long 


ЧА) as | reum aderess | on 


Parameter 
block 


(sp —> 


Figure 5 Local stack for PutSerial 


These serial I/O routines are lacking in a few features 


<6- -pBlock(a6) 


handles and pointers in unused CPU registers. Since I don't 
know what you plan to do with Term, I've tried to minimize the 
use of registers for handle storage. Most of the menu and window 
handles are kept as global variables. 

Macintosh applications often share the same basic structure 
and even some of the initialization and event parsing routines. 
Term is no exception. It is a quilt of routines that have been 
borrowed from other applications. Term begins by initializing 
the modem port and going through the usual ritual of setting up 
things and initializing managers. It finishes the initialization by 
copying the contents of the clipboard to the TextEdit scrap. Term 
ends when a non-zero value is passed to the event loop, either 
when the user selects Quit from the menu or clicks іп the program 
window's close box. Term then cleans up, resets the input buffer 
back to its default size and returns to the Finder. 

Since Macintosh programs spend most of their time in the 
event loop, this is the best place for Term to check the modem port 
and display any new characters that may have been received. 
You may notice that the EventRecord is declared and used as a 
global variable. It used to be a common practice to declare the 
EventRecord as a constant; this saved a few keystrokes when 
typing in the program. The practice did notcause problems when 
the program was running because the 68000 doesn't make any 
distinctions between the memory used for variable storage and 
that used for constants and code. With the 68020, 68030 and 
future CPUs, memory management becomes part of the com- 
puter hardware. With an MMU, an operating system could set 
aside memory to be used as storage for a program's code and 
constants... and declare this memory to be read only. Imagine the 
surprise of a program trying to write to a write-protected Even- 
tRecord! 


(mainly better and more complete error checking) but since the 
interface to the calling program (be it a high level language or 
assembly) is consistent, these routines can be used as the basis for 
more complete routines, or used as-is, without any major changes 
to the calling program. 


Using the Serial I/O Routines in the Real World: 
An Example 
The easiest way to learn how to use the serial I/O routines is 
with an example. Term is an extremely simple terminal program; 
it sends characters typed at the keyboard out the modem port and 
uses TextEdit to display the incoming characters. Besides the 
standard File and Edit menus, Term has a Command menu with 
an Erase Screen item and four (300, 1200, 2400 and 9600) baud 
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Term Routines 
Instead of a detailed description of every routine in Term, I'll 


focus on the routines that make it different. 


PutScreen filters the characters in the input buffer, IOBuf, 


and transfers the displayable characters to Outbuf, the output 
buffer. The variable CharCnt is used to tell TextEdit how many 
characters are in the output buffer. 


À communications program must be able to display charac- 


ters on the screen quickly, especially at the higher baud rates, 
when data may be flooding in through the serial port. On the 
Macintosh, the quickest way to get a character on the screen is to 
use QuickDraw's DrawChar function, and this is what I used in 
the early versions of Term. Unfortunately, DrawChar does little 
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else besides drawing a character on the screen. Alltext manipu- 
lations (simple things like backspace and carriage return) must be 
handled with a stupendous amount of code. I knew that TextEdit 
could handle some of these simple functions, and TextEdit had 
the extra bonus of making it easy to cut and paste the text to the 
clipboard and back. Unfortunately, TextEdit is extremely slow. 
My initial attempts to use TextEdit were a miserable failure; I was 
losing most of the incoming data. The solution, of course, was 
to increase the size of the serial input buffer. 

While TextEdit is an improvement over DrawChar, it will 
only recognize a limited number of control characters, so 
PutScreen must deal with any control characters it finds in IOBuf. 
In this version of PutScreen, only the carriage return (CR), Bell, 
Tab and backspace (BS) characters are recognized; all other 
control characters are discarded. By replacing the simple com- 
pare and branch code with a lookup table, PutScreen could be 
made to emulate a real terminal, like the VT-52 or VT-100. 

PutScreen lets TextEdit handle carriage returns. To back- 
space, PutScreen decrements the output buffer pointer by one (to 
erase the previous character) and decrements the character count 
by two (to account for the deleted character and the backspace 
character). If the character count is zero, then no characters have 
to be displayed, and PutScreen passes control to the NextEvent 
routine. If CharCnt is greater than zero, there are still characters 
to be processed, and PutScreen goes on to the next character in 
IOBuf. If the CharCnt is less than zero, we are no longer dealing 
with "fresh" characters and must delete a character that has 
already been displayed. To do this, PutScreen passes the BS 
character directly to the TEKey trap, which deletes the last 
character displayed. It then passes control to the NextEvent loop. 

If the control character is a Bell (control G) PutScreen will 
generate a short beep, decrement the character count, and con- 
tinue with the filtering. 

Tabs are hard coded for five spaces. PutScreen places five 
spaces in the output buffer and increments the character count by 
four (we don't want the tab character itself to be displayed) before 
continuing with the filtering. 

Displayable characters are transferred from the IOBuf to the 
OutBuf, and the filtering continues until all the characters have 
been dealt with. PutScreen then uses  TEInsert to pass the 
OutBuf to TextEdit, which displays it. PutScreen also calls 
_TESelView, to scroll the window, if needed. 

KeyDown takes characters typed at the keyboard and saves 
them in IOBuf. If the command key is pressed, it converts the 
character to a control character, and inserts it into the IOBuf. 
KeyDown then sends the character out the modem port. 

InBaud is used to change the baud rate. This routine 
unchecks the previous menu item, checks the new one and sets 
the new baud rate, using the Config routine. 


Possible Enhancements 
Like most programs, Term has room for improvements. The 
easiest additions would be to make the window resizable and 
make the program MultiFinder friendly. 
Term will operate at 19,200 baud; I was just too lazy to add 
it as a menu option. A menu option to change the default port 
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might be useful, but dangerous. Since the printer portis used with 
networks and printers, the routine to switch ports must check to 
see if AppleTalk is active or if the printer port is being used by 
another program. 

A slightly more difficult task would be to have Term send 
text pasted in it’s window, from the Clipboard, out the serial port. 
Another TextEdit related problem is a cosmetic one; I imple- 
mented a screen erase function in Term by clearing out the all the 
data іп the TextEdit record. It works, but it makes the screen flash 
like an IBM PC screen...somewhat disconcerting. 

A final improvement would be to add a file transferring 
capability, using the MacBinary extension to the XMODEM 
protocol. This wouldn't be as difficult as it sounds; both the 
MacBinary and XMODEM protocols are well described. It 
would be a good idea to increase the input serial buffer to at least 
1280 bytes, room enough to fit a 1K XMODEM block. This 
would speed up the data rates by allowing the program to work 
on one block of data while another block is being received in the 
background. 


Borrowed Routines 

A few ofthe routines and techniques that Iused in Term were 
borrowed from other programs. The code to deal with the 
clipboard is a slightly modified version of the code in the 
Clipboard chapter in Dan Weston's "The Complete Book of 
Macintosh Assembly Language Programming, Volume II." 
Some of the ideas on how to handle TextEdit came from Dan's 
“Тһе Complete Book of Macintosh Assembly Language Pro- 
gramming, Volume I." It should be pretty obvious that these are 
two very useful (if somewhat dated) books on Macintosh assem- 
bly language programming. 

Victor Barger's Rose Curve Generator program is an excel- 
lent example of good code layout and presentation. I've tried to 
make Term as easy to read. 


References 

Dan Weston, "The Complete Book of Macintosh Assembly 
Language Programming" Volumes I and II. 

Victor Barger, "Rose Curve Generator," MacTutor, January 
1987 

Apple Computer, "Inside Macintosh" volumes I - V (mainly 
volumes I and II) 

Apple Computer, Technical Note 130, ioCompletion 

Kirk Austin, “A MIDI Library for Pascal," MacTutor, July 1987 

Kirk Austin, "MIDI Demo uses MIDI Library," MacTutor, 
December 1987 


Listing: tera.job 

asm term.asm execedit 
link term.link execedit 
rmaker term.r termedit 


Listing: tera. link 
/Output term.code 


/Type ‘TEMP’ 42222” 


term 
бегі/0 
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;A11 done 
/End 


Listing: SerI/0.asm 


; File: SerI/0.asnm 


; SerI/0.asm consists of following stand-alone serial I/0 
routines: 
; Function OpenSerial(Port: integer): OSErr 
; Function Config(Port, SerVal: integer): OSErr 
; Function GetSerial(Port: integer; buffer: pointer): CharCnt 
; Function PutSerial(Port: integer; CharBuf: pointer; count: 
longint): OSErr 
; Function SetBuf (Port: integer; BufSiz: long): OSErr 
; Port refers to port reference number, which is -6 for modem 
; input port (port A) or -8 for printer input port (port B) 
‚ For description of how to write modular assembly language 
; routines see Weston’s "Complete Book of Macintosh Assembly 
; Language Programming Volume I^, Appendix D 

1/14/88 Working version of the routines 
written by Frank Henriquez 


Register usage: 

00: general purpose. 

di, d2, d3, 44, d5, 46, d7 : not used. 

að: general purpose, used for buffers and parameter blocks. 
al: general purpose. 

82, a3, a4: not used. 

86: used as the local stack frame pointer 

ab, а? : system use. 


e Wwe We We We We We Be We %.. We. We Ww ~ ` ~ ~ ` 


Include 
Include 


Traps .D 
SysEqu .D 


ХОЕР OpenSer ial 
XDEF Conf ig 
XDEF GetSer ial 
XDEF PutSer ial 
XDEF SetBuf 


; equates for each stack frame 
pBlock equ -ioQelSize 


OpenPar equ 2 ; OpenSerial - # of parameter words on stack 
OpenRes equ 10 ; OpenSerial - offset to result word 
OpenPort equ 8 ; OpenSerial - offset to Port Reference 8 


ConfPar equ 4  ; Config - # of parameter words on stack 
ConfRes equ 12 ; Config - offset to result word 
ConfPort equ 10 ; Config - offset to port Reference # 
ConfVal equ 8 ; Config - offset to port config value 


GetPar equ 6  ; you've probably figured the pattern 
GetCnt equ 14 ; offset to character count 

GetPort equ 12 ; out by now... 

GetBuf equ 8 ; offset to character buffer pointer 


PutPar equ 10 
PutPort equ 16 
PutBuf equ 12 
PutCnt equ 8 
PutRes equ 18 


offset to character buffer pointer 
offset to character count pointer 
dummy result 


we We 


we 


SetPar equ 6 
SetRes equ 14 ; offset to SetBuf result word 
SetPort equ 12 
SetSiz equ 8 ; offset to new buffer size 


; misc. equates 


SerReset equ 8 ; from Inside Macintosh 
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SerSetBuf equ 9 
ioNamePtr equ 18 


; from Inside Macintosh 
; missing from MDS 


; OpenSer ial 
; Opens the modem port for reads and writes. 
; Function OpenSerial(Port: integer): OSErr 


OpenSer ial 
link аб, #pB lock ; local space for parameter block 
lea pBlock(a6),a8  ; point to parameter block 
lea '.AIn^,al ; assume port A input 
cmpi.w 8-6 OpenPor t(a6) ; Open port B if not -6 (port A) 
beq.s 81 
lea '.Bin^,al 
61bsr.s Openit 
lea '.A0ut^,al 
cmpi.w 8-6 OpenPor t(a6 ) 
beq.s 62 
lea ‘.Bout’,al 
62bsr.s Openit 


; Open port B input 


; assume port A output 


; Open port B output 


OExit move.w 90, OpenResCa6) 
errors 
-KilllO 
илік аб 
move.] (өр2%,а0 
addq. 1 #0penPar, sp 


; procedure returns а Ø if no 


; kill any pending calls 

; discard local stack area 
; get return address 

; Clean up stack 


jmp (ай) end of InitSerial 
Openit 
move.] a1, ioNamePtr (ad) ; tell the Device Manager which 
_Open ; port to open 
rts 
;— — Configure ports 


; Sets the Port to the baud rate, data length, 
; parity, stops, etc. held in SerVal. 
; Function Config(Port, SerVal : integer) : OSErr 


Conf ig 
link аб, ®pB lock 
lea pBlock(a6),ad 


; local space for parameter block 
; point to parameter block 

move.w ConfPort(a6),d8 ; get Input Reference number 
bsr.s doConf ; configure the input side 

tst.w (0 ; check for errors and 

bne.s CExit ; exit with the error flag in 00 
move.w ConfPort(a62,d0 ; get Input Ref number 

subq.w 81,040 ; and make it the output ref num 
bsr.s doConf ; configure the output side 


CExit move.w d2,ConfRes(Ca6) 
опік аб 
поуе.1 (sp)+,a0 
eddq.1 *ConfPar,sp 
jmp (að) 


; Save result 


; and clean up the stack 
; end of Configure 


doConf move.w dO, ioRefNumCa0) ; port # 
move.w SerReset,csCode(a0) ; reset port to 
move.w ConfVal(a6),csParam(a0) ; these new settings 
-Control 
rts 


;j——Y — SetBuf 
increases the size of the Port input buffer 
Function SetBuf CPort:Integer; BufSiz:long):OSErr 


me 


me 


SetBuf link аб, #рВ1оск  ; local space for parameter block 
поуе.1 SetSiz(a6),d8 


beq.s 81 ; if size = 0, reset input buffer 
-NewPtr ; get a nonrelocatable block 
tst.1 d? ; abort if couldn't get it 

bne Exit 


move.] а0,а1 ; save block ptr in al 
поуе.1 SetSiz(a60,d0 . reload the buffer size 
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@llea pBlock(a6),a0 ; point to parameter block 
move.w SetPort(a6),ioRefNum(a0) 
move.w ®SerSetBuf , csCodeCa0) 
поуе.1 al,csParam(a@) ; pointer to new buffer 
move .w 00, сѕРагат+4(ай ) 
Control 

Exit move.w dð, SetResCa6) 
unlk аб 
поуе.1 (sp)+, ай 
addq.] 8SetPar,sp 
jmp (ad) 


; standard exit routine 


; end of SetBuf 


f GetSerial 

; GetSerial checks the Port to see if anu 

; characters have been received, and proceeds 

; to read them into the input buffer. 

; If none have been received, GetSerial returns 

‚ай in the character count variable. 

; Function GetSerial(Port: integer; buffer:pointer) : CharCnt: 
long 


GetSerial 
link аб, #pBlock 
lea pBlock(a6), ad 
move.w GetPortCa6), ioRefNumCa) 
move.w 82 csCodeCa0) ; call SerGetBuf 
-Status 
поуе.1 сѕРагатСай ), 00 
поуе.1 d@,GetCnt(a6) 
beq.s 62 


; get # of characters received 


; if none, then leave, if there are 
; characters available, read them. 
@ imove.w GetPort(a6), ioRefNumCa2) 

поуе.1 GetBuf (a6), ioBufferCa®) ; the input buffer 

поуе.1 40, ioReqCount Кай) ; read the characters 


-Read 

@2unlk аб ; Standard exit routine 
move.] (sp)+,að 
addq.1 #GetPar,sp ; leave char count on stack 
jmp (að) ; end of GetSerial 

У PutSerial 


; PutSerial sends the characters in the buffer 

; out the Port. This routine is pretty 

; primitive - it ignores anu pending writes 

; and errors, but...it works. It returns a dummy result. 

; function PutSerial(Port: integer; CharBuf:pointer; count: 
pointer): OSErr 


PutSerial 
linka6,#pBl1ock 
lea pBlock(a6),a0 


; local space for parameter block 
; point to parameter block 

move.w PutPort(a62,d0 — ; get the port ref 8 

subq.w 81,00 ; make it the port output ref num 
move.w dð, ioRefNumCað) ; modem output port 

поуе.1 PutBuf (a6), ioBuffer(a0) ; point to buffer 

тоуе.1 PutCnt(a6),a! ; get pointer to char count 
поуе.1 (a1), ioReqCount(ad) ; and put char count here 
Write 

move .w 80 PutRes(a6) 
илік аб 

поуе.1 (sp)+,ad 
adda.] ®PutPar,sp 
jmp (að) 


; save a 0 as a dummy result 
; standard exit routine 


; end of PutSerial 
Listing: term.asa 
File: Term.asm 


Term.asm is simple terminal program, shows how to use low 
level serial I/0 routines. 

written by Frank Henriquez 

code that handles transfers between clipboard and Text Edit 
is based on the code in chapter 3 of Dan Weston’s “Complete 
Book of Macintosh Assembly Language Programming Vol. II^ 
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Some coding ideas were borrowed from the program “Rose.Asm” 

by Victor Barger, appeared in Jan. 1987 issue of MacTutor. 
1/15/87 Initial Turbo Pascal version, using Quickdraw. 
9/1/87 assembly language translation. 

10/10/87 modified to use TextEdit. 

10/18/87 fully functional version. 

10/20/87 text handling improved, Baud rates added. 
1/14/88 modified to use external serial I/0 routines. 


Register usage: 

dð: general purpose, also holds the menu't. 

dl: general purpose, also menu item? and the Modify value. 
d2: general purpose. 

d3, d4, 45, d6, d7 : not used. 

ай: general purpose, used for buffers and parameter blocks. 
al: general purpose. 

82: holds TextEdit handle. 

83: general purpose. 

84, a6 : not used. 

ad, а? : system use. 


pre-compiled routines from Serial I/0.asm 


XDEF OpenSer ial 
XDEF Conf ig 
XDEF GetSer ial 
XDEF PutSer ial 
XDEF SetBuf 


‚ Standard include files 


Include Traps.D 
Include Toolequ.D 
Include Sysequ.D 
Include Quickequ.D 


ÁppleMenu equ 1 
AboutItem 


Program constants 
; Apple 
equ 1 ; First item in Apple menu 


FileMenu equ 2 ; File 
1 


QuitItem еди 


EditMenu equ 
UndoItem equ 


; First item in File menu 


; Edit 
Items in Edit menu 


we 


CutI tem equ 


PasteItem equ 
ClearItem equ 


3 
1 
3 
CopyItem equ 4 
5 
6 


CmdMenu equ 4 ; Command menu 


Eraseltem equ 1 


Erase screen 


~ . 


B300 equ 3 ; 300 baud 

B 1200 equ 4 ; 1200 baud 
B2400 equ 5 ; 2400 baud 
B9600 equ 6 

AboutDialog equ 1  ; About dialog 
ButtonItem equ 1  ; First item in DITL 
WindID equ 1 

PortA equ -6 

PortB equ -8 

baud300 equ 380 

baud 1200 equ 94 

baud2400 equ 46 

baud9600 equ 10 

stop 10 equ 16384 

noParity equ 8192 

data8 equ 3072 
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Conf ig300 equ baud300 


+ data8 + stop10 + noParitu 


СопҒі01200 еди baud1200 + data8 + stopið + noParity 
Config2400 еди baud2400 + data8 + ѕіор10 + noParity 
Conf 1096004 equ baud9600 + data8 + ѕіор10 + noParitu 


: Program starts here ———— 


Start 
bsr.s InitSerial 
bsr InitManagers 
bsr SetupMenu 
bsr SetupWindow 
bsr SetupTextEdit 
bsr CliptoTE 


EventLoop 
-SystemTask | 
move.] a2,-(sp) ; 
-TEIdle ; 
bsr GetSerCh 3 
bsr PutScreen ў 
clr.w -(sp) 
move.w #%$0fff,-C(sp) ; 
pea EventRecord(a5) 
-GetNextEvent ; 
move.w (sp)+, dø 
beq.s EventLoop Jj 
bsr HandleEvent 
beq.s EventLoop f 
тоуе.1 a2,-(sp) 
-TEDispose 
clr.w -Csp) 
move.w "PortA,-Csp) ; 
clr.1 -Csp) | 
jsr SetBuf 
addq.1 82 өр 
-ExittoShell 


; InitSerial 


; check for DA calls 
; get handle to text record 


blink cursor etc. 


; get a character from the modem port 
; end put it on the screen 


look for all events 


get the next event (WaitNextEvent!?) 


loop until an event 


; take care of the event 


time to quit if not zero 


modem port 
reset default serial buffer 


; Open serial port for reads end writes, set 
; the baud rate to 1200 baud and increase the 
; Size of the serial input buffer to 512 bytes 


InitSerial 
clr.w -(sp) 
move .м ®Por tA, -(sp) 
jsr OpenSer ial 
tst.w (sp) 
bne.s Abort 
move .w ®Por tA, -Csp) 


move .w ®Conf ig 1208, - (sp) 


jsr Config 

tst.w (sp) 

bne.s Abort 

nove.w *PortA, -Csp) 
поуе.1 #512,-(sp) ; 
jsr SetBuf 
move .w (sp)+, а0 
bne.s Abort ; 
rts 


: Abort 

Abort 
move .w 830,-(sp) 
_Sysbeep 
-ExitToShe1]1 Р 


; InitManagers 

InitManagers 
-MoreMasters ) 
move.] #$ffffffff ,d0 
-NewHandle : 
pea -4(а5) j 
_InitGraf 
-InitFonts 
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; room for routine results 
; Open the modem port (Port A) 


; if Open failed, beep and quit. 


; Set modem port to 1200 baud 
; if Config failed, beep and quit. 


; make the serial input buffer 
512 bytes big. Prevents data loss. 


; clean up the stack, and abort if 


SetBuf failed. 


jump back to Finder 


prevents heap fragmentation 


compact heap 
QuickDraw globals 


move.1 t'$0000f fff , dO 
-FlushEvents 
-InitWindows 
_InitMenus 

clr.1 -(5р) 
-InitDialogs 
-TEInit 

_InitCursor 

rts 


; flush all events 


; no restart procedure 


3 SetupMenu 

SetupMenu 

¿Apple menu: 
clr.] -€sp) 
move.w *AppleMenu, -(sp) 
—GetRMenu 
move.] Csp2,AppleMHdlCa5) 
move.] Csp2,-Csp) 
clr -(sp) 
-InsertMenu 
move.] ®’DRVR’,-Csp) 
_AddResMenu 


; save handle to menu 


; add DA’s to Apple menu 


;File menu: 
clr.] -(sp) 
move.w #FileMenu,-(sp) 
-GetRMenu 
тоуе.1 (sp),FileMHdl(a5) ; save handle to menu 
clr -Csp) 
-Inser tMenu 


¿Edit menu: 
clr.] -(5р) 
move.w #EditMenu,-(sp) 
-GetRMenu 
move.) Cspo,EditMHdl(a5)  ; save handle to menu 
clr -Сөр) 
-Inser tMenu 


Command menu: 
с1г.1 -(sp) 
move.w #CmdMenu,-(sp) 
-GetRMenu 
move.1 (sp),CmdMHd](a5) ; Save handle to menu 
clr -(sp) 
_Inser tMenu 
move.] CmdMHd1Ca52,-(sp)  ; put handle on stack 
move.w 88 1200, 00 
move.w 00 ВауаСһк(а5) 
move.w d@,-(sp) 
move.w ®-1,-(sp) 
_CheckI tem 
-DrawMenuBar 
rts 


; next to the 1200 baud item 


; SetupWindow 
SetupWindow 
clr.] -(sp) 
move.w #WindID,-(sp) 
pea WindowStorage(a5) 


move.] #-1,-(sp) ; make it the top window 


-GetNewWindow ; load it from the rsrc file 
move.] Csp),WindowHdl(a5) ; save handle 
-SetPort ; make it the current port 
move.w monaco, - (sp) ; Monaco 
—TextFont 
move .w #9, -(5р) ; in 9 pt. 
-Техібіге 
rts 
; SetupTextEdit — Oa [ 
SetuplextEdit 
с1г.1 -(sp) ; space for text handle 


pea DestRect ; DestRect Rectangle 
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; get Apple menu from the rsrc file 


pea ViewRect 
_TENew 

поуе.1 (sp)+,ad 
тоуе.1 ай, a2 | 
тоуе.1 (a0),a0 
move.b #-1,teCROniu( 
move.w #-1,-(sp) 
поуе.1 a2,-(sp) 
_TEAutoView 

rts 


;———n CliptoTE 
; CliptoTE 


CliptoTE 
поуе.1 80 аз 
bsr.s 61 
bmi.s 82 


move.] 80 00 
-NewHandle ; 
move. ай, аЗ 

bsr.s 81 


in a2 


ай) 


; ViewRect Rectangle 


; Save text handle 


; enable TE auto scroll (128K ROM) 


copies text in the clipboard to the TE scrap 


; Check for TEXT in the desk scrap 
; leave if none 


; lets get the scrap, but first 


get a handle for it 


поуе.1 ТЕбсгрНапа1е,а0  ; 


-DisposHandle 
поуе.1 a3, TEScrpHand 


le ; 


поуе.1 TEScrpHandle, ad 


_GetHandleSize 
move .w dð, TEScrpLeng 
e2rts 


бісіг.1 -(sp) 
move. a3,-(sp) 
поуе.1 ®’TEXT’,-Csp) 
pea CSOffset(a5) 
-GetScrap 
пое. 1 (sp)+,d@ 


th 


rts 
j GetSerCh ----- 
GetSerCh 

clr.] -(5р) 


move.w ®PortA, -(sp) 
pea IOBuf(a5) 
jsr GetSerial 
move.] (sp)+,CharCnt 
bra NextEvent 

; PutScreen 


replace old handle to TEScrap 
with ours 

get length of our scrap 

leave CliptoTE 

space for result 


just check for TEXT 


return result 


; room for character count 
; if modem port has data, save it 
; in this buffer. 


(85) 


; get 8 of characters received. 


; PutScreen will display the characters in 
; the buffer, taking care of some control 
; characters. It uses TextEdit for display. 


PutScreen 
move.1 CharCnt(a5),d 
beq NextEvent 
Subq.1 *1,d1 


PutTE lea IOBuf(a5),a0 


lea OutbufCa52,al 
ТЕГ оор move.b Ca20)*,d0 
andi .w 8%7Ғ,00 
cmpi.w 8%20 040 
blt.s CtrICh 
inBuf move.b d0,(a1)+ 
inLoop дога d1,TELoop 
pea Outbuf Cad) 
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Skip if no characters in buffer 


; edjust character count for loop 


f point to the character buffers 


get a char from the input buffer 
clear out 8th bit 

if less than space, then it 

must be a Ctrl character 
printable character 


; print the sanitized output buffer 


move.1 CharCnt(a5),-(sp) 


поуе.1 a2,-(sp) 
_TEInsert 
move.] a2,-(sp) 
-TESelView 

bra NextEvent 


:— handle control characters 


; Scroll if needed 
; exit PutScreen 


Control characters are serviced here. A 
; lookup table would be more efficient, in 
; particular if we were to emulate a real 
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Ctr1Ch cmpi.w 8%04,00 


beq.s 


inBuf 


cmpi.w #8,d0 

beq.s BS 

cmpi.w 87,00 

beq.s Bell 

cmpi.w 89 00 

beq.s Tab 

subq.1 * 1, CharCnt(a5) 


bra.s 


inLoop 


BSsubq.1 #1,a1 
Subq.1 2, CharCntCa5) 
beq NextEvent 


bgt.s 


inLoop 


move.w d,-(sp) 
move. a2,-(sp) 
_ТЕКеу 

bra NextEvent 


Bellmove.w 830,-(sp) 
-SysBeep 
Subq.1 * 1, СћагСпіСа5 ) 


bra.s 


inLoop 


Tab move.w 84,42 
@lmove.b 8%20 (а1)+ 
dbra (2,061 

addq.] #4,CharCnt(a5) 


д 


bra.s 


inLoop 


Handle Event 


4 


we We ~ . we we We we We We We 


we 


; terminal (like а VT-52 or VT- 100). 


, let Text Edit take care of CR 


backspace 
bell 
tab 


ignore anything else 


move back outbuf pointer by 1 


1 for BS char, 1 for erased char 


no chars to print - all done. 
continue filtering 


use TEKey to force backspace 
if backed out of input buffer 


make a beep 

get rid of character 

5 spaces for a tab 

put them into the output buffer 


adjust the character count 


; © * spaces, -1 for the tab char) 


; This routine is the core of the program. 
; The event number is used as an index into 
; the EventTable. These entries cover all 

; the events that could happen while the 


д 


HandleEvent 

move.w Modify(a5),d1 
move.w What(a5),d0 

add.w 00,90 

move.w EventTable(d@), dø 
jmp EventTableCd0) 


EventTable 


д 


.w NextEvent-EventTable 
.w MouseDown-EventTable 
.w NextEvent-EventTable 
.w KeuDown-EventTable 
.wNextEvent-EventTable 
.w KeyDown-EventTable 
.wUpdate-EventTable 
.wNextEvent-EventTable 
.W Activate-EventTable 
.w NextEvent-EventTable 
.w NextEvent-Event Table 
.w NextEvent-Event Table 
.w NextEvent-EventTable 
.w NextEvent-EventTable 
.w NextEvent-EventTable 
.w NextEvent-Event Table 


Mouse down 


MouseDown 

clr.w -(sp) 

поуе.1 Point(a5)2,-Csp) 
pea WWindow(a5) 
FindWindow 

move (sp)+,d0 


7 


4 


; program is in the main loop. 


; get event number 
; *2 for table index 


; point to routine 
; and jump to it 


9 (Null) 

1 mouse down 

2 mouse up (Not used) 
3 key down 

4 key up(Not used) 

5 auto-key 

6 update 

7 disk inserted (Not used) 
8 activate 

9 abort (Not used) 

network (Not used) 

1/0 driver (Not used) 
applEvt (Not used) 
app2Evt (Not used) 
app3Evt (Not used) 
app4Evt Csuspend/resume? ) 


"8 We We We We We We We We We We We We We We 


‚ space for result 


4 


2 
; get mouse coordinates 


Event Window 


get region number 
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add d£,d0 ; *2 for index into table 
move.w Windowlable(d@),d@ ; point to routine offset 
jmp Windowlable(d0) ; jump to routine 


dc.w NextEvent-WindowTable 


Windowlable 
dc.w NextEvent-Windowlable ; In Desk (Not used) 
dc.w InMenu-Windowlable ; In Menu Bar 
dc.w SustemEvent-Windowlable ; In Sustem Window 
dc.w Content-WindowTable ; In Content 
dc.w Drag-WindowTable ; In Drag 
dc.w NextEvent-WindowTable ; In Grow (Not used) 
dc.wQuitRoutine-WindowTable ; In Go Away 


dc.w NextEvent-WindowTable 


^ in Menu 
InMenu 
clr.] -(Csp) ; make room on stack 
move.] Point(a5),-(sp)  ; mouse event 
-MenuSelect 
move.w (sp)*,dO ; Save menu 
move.w (sp)+,d1 , &nd menu item 
Choices ; called by command key too 
cmp.w #AppleMenu,d0 
beq.s InAppleMenu 
cmp.w Е і1еМепи, 80 
beq.s InFileMenu 
cmp.w ®EditMenu, d 
beq.s InEditMenu 
cmp.w ®CmdMenu, а0 


beq InCmdMenu 


ChoiceReturn 


7 
2 
д 


bsr UnHiliteMenu 
bra NextEvent 


; unhighlight the menu bar 


in InAppleMenu 


In the Apple menu. If it wasn’t About, it must have been a 


desk accessory. If so, open the desk accessory. 


InAppleMenu 


cmp.w fAboutItem,d1 ; is it About? 

beq.s About ; if so go do About... 
move.1 AppleMHd1Ca52,-Csp) ; look in Apple Menu 
move.w di,-(sp) 


pea DeskName(a5) ; get Item Name 
-GetItem 
clr -(sp) , Space for opening result 
pea DeskName(Ca5) ; open Desk Acc 
_OpenDeskAcc 
move .w (sp)+,d0 ; pop result 

GoSetOurPort 


bsr SetOurPort 
bra.s ChoiceReturn 


About 

Set up the About dialog box, and wait for 
the proper click or keypress. End bu 
closing the dialog box and setting the 


port to us. 
About 
clr.] -(sp) ; Space for dialog pointer 


move #AboutDialog,-(sp) ; dialog rsrc # 

pea DStorage(ad) 

тоуе.1 ®-1,-(sp) ; dialog goes on top 
-GetNewDialog 

move.] Csp2,-Csp) ; copy handle for Close 
-SetPort make dialog box the port 
поуе.1 a2,-(sp) 

-TEDeAct ivate 


“. 
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Іп Zoom іп box (Not used) 
In Zoom Out box (Not used) 


WaitO0OK 
clr.1 -(5р) ; Clear space for handle 
pea ItemHit(a5) 


-ModalDialog ; wait for a response 
move.w ItemHit(a5),d0 ; look to see what was hit 
cmp.w fi«ButtonItem,d0 ; wes it OK? 

bne.s WaitOK 

-CloseDialog ; handle already on stack 
bra.s GoSetOurPort 


i in FileMenu 
inF ileMenu 

cmp.w fQuitItem,d1 
bne.s ChoiceReturn 
bsr UnHiliteMenu 
bra RealQuit 


is it Quit? 

no, go get next event 
unhighlight the menu bar 
go Quit 


wee We We We 


in EditMenu 
The Edit Menu support routines transfer the 
TE scrap to the clipboard, and back. See the 
clipboard chapter in Dan Weston’s 
“Assembly Language Programming Volume II^ 


"-— Be We We Be 


InEditMenu 
bsr SystemEdit 
bne.s ChoiceReturn 
cmp.w *"i'CutItem,d1 
beq.s Cut 
cmp.w ®Copyltem,d! 
beq.s Copy 
cmp.w "PasteItem,d1 
beq.s Paste 
cmp.w ?iClearItem,d1 
beq.s ClearIt 
bra ChoiceReturn 


; Desk accessory active? 
; yes, SystemEdit handled it 


осо = о = о = О ж О 


Cut 
поуе.1 a2,-(sp) 
-TECut ; Cut and copy text 
bra.s Convert 


Copy 
move.] a2,-(sp) 


-ТЕСору ; Copy text to scap 
bra.s Convert 


Paste 
bsr CliptoTE ; from the clipboard 
move.] a2,-(sp) 
_TEPaste ; Paste 
bra ChoiceReturn 


ClearIt 
move.1 a2,-(sp) 
_TEDelete ; Clear without copying 


Convert 
bsr.s TEtoClip ; copy to clipboard 
bra ChoiceReturn 


; TEtoClip ------ 
; TEtoClip copies the TE scrap to the Clipboard 
TEtoClip 
move.] TEScrpHandle, ad 
_GetHandleSize ; get length of our scrap 
поуе.1 d2,a3 ; save length 
clr.1 -(sp) ; Space for result 
_ZeroScrap ; want to write over scrap 


поуе.1 (sp)+,d0 

move.] TEScrpHandle, ай 

-Hlock ; lock pointer to our scrap 
сіг.1 -(5р) ; Space for result 
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move.] a3,-(sp) 

move.] ®’TEXT’,-Csp) ; just check for TEXT 
поуе.1 TEScrpHandle, ай 

move.] (a0),-(sp) ; Save pointer to TE scrap 
~PutScrap 

тоуе.1 (sp)+, dð 

move.1 TEScrpHandle,að 


-HUnLock ; unlock handle 
rts ; leave TEtoClip 
; in CmdMenu 
InCmdMenu 


cmp.w #Eraseltem,d1 ; baud rate change? 
bne.s InBaud 


; it wasn’t baud change command, fall through to erase screen 


поуе.1 80 ,-(sp) 
поуе.1 8$ffff,-Csp) 
поуе.1 a2,-(sp) 
-TESetSelect 

bra.s ClearIt 


; Set Selection range to cover 
; everything in this TE block. 


; and clear them out 


in BaudMenu 


InBaud 

cmp.w #B300,d1 
beq.s 81 

cmp.w 881200,01 
beq.s 82 

cmp.w 88240041 
beq.s 63 

cmp.w #B9600,d1 
beq.s 84 

bra NextEvent 


e 1move.w #Conf 19300, SerConCab5) 
bra.s 65 

@2move .w Conf ig1200, SerConCa5) 
bre.s 65 

@3move.w Conf ig2400, SerConCa5) 
bra.s 65 

64move.w ®Conf 159600, SerConCa5) 

85move.1 CmdMHd1(a5),-Csp) 
move.w BaudChk(a5),-Csp) ; uncheck previous item 
move.w д1, BaudChk(a5 ) ; Save new baud item 
move.w 80,-(sp) 
-CheckItem 
тоуе.1 CmdMHd1(a5),-Csp)  ; put handle on stack 
move.w BaudChk(a5),-(sp)  ; and place a check 
move.w #- 1,-Сѕр) ; next to the current baud 
-Check I tem 
clr.w -(sp) 
move.w ®Por tA, -Csp) ; set the new baud rate 
move .w SerCon(ad),-(sp) 
jsr Conf ig 
move.w (sp )+, ай р 
bra ChoiceReturn 


ignore the result 


У UnhiliteMenu 
UnhiliteMenu 
clr.w -(sp) ; а11 menus 
~HiLiteMenu 
rts 


| SystemEdit ————— 
SystemEdit 

clr -Csp) 
move.w d1,-Csp) 
ѕира * 1, Сер) 
-SysEdit 
move.b Csp2*,d0 
rts 


; Space for result 
; get item in Edit menu 
; SystemEdit is off by 1 


Р SustemEvent 
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SustemEvent 
pea EventRecord(a5) 


поуе.1 WWindow(a5),-(sp) 


—SustemC]ick 
bra NextEvent 


in Content 


М 

Content 
clr.) -(sp) 
-FrontWindow 
move.] Csp2*,d0O 


стр.1 WindowHdl(a52,d0 


beq.s 61 


move.] WWindowCa5),-Csp) 


-SelectWindow 
bra NextEvent 


біреа Point(a5) 
-6lobalToLocal 
move.] PointCa5)2,-Csp) 
btst 39 di 
sne dø 
move .b dð, -(sp) 
move.] a2,-(sp) 
-TEClick 
bra NextEvent 


; in Drag 
Drag 


move.1 WWindowCa5),-(Csp) 


тоуе.1 Point(a5),-Csp) 
pea WBounds 
_DragW indow 
bra NextEvent 


; Quit Routine 
QuitRoutine 
clr.w -(sp) 


тоуе.1 Point(a5),-(sp) 
_TrackGoAway 

move.w (sp)+,d0 

beq NextEvent 


RealQuit 


let the system do it 


room for result 


; front window pointer 


4 


7 
, Same as our pointer? 


; ignore it 


; do it, fall through to NextEvent 


4 


move.] WindowHd1(a5),-(sp) ; 


-CloseWindow 
move.w #-1,d0 
rts 


; Keu down 
KeuDown 


move.w Message+2(a5),d0 


btst #8,d1 
beq.s SaveCh 
andi .w "$20 1f , 90 


SaveCh move.b dø, [0Buf (a5) 


поуе.1 * 1, CharCntCa5) 
clr.w -(sp) 

move.w 'PortA,-Csp) 
реа IOBuf(a5) 

pea CharCnt(ad) 

jsr PutSer ial 

move.w (ер2%,00 

bra.s NextEvent 


К Update 
Update 


we `. We We `. We We We 


we 


we 


move.] WindowHd1(a5),-(sp) 


-BeginUpdate 
pea ViewRect 
-EraseRect 

pea ViewRect 
поуе.1 a2,-(sp) 


; drag window and fall through 


; room for result 
move.] WindowHdl(a5),-(Csp) ; 


get pointer to open window 


; mouse point 


didn't really want to quit 


did want to quit 
00 is TRUE - ok to quit 


get key code and character 
command key pressed? 

yes, take care of it. 

convert to a control character 
save it in the buffer 

send the character typed 

room for dummy result 

in the input buffer 


and send it out the modem port 
get rid of dummy result 


; erase visible window 
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_TEUpdate 

поуе.1 WindowHd1(a5),-Csp) 
_EndUpdate 

bra.s NextEvent 


Р Activate 
Activate 
поуе.1 WindowHd1(a5),d@ 
стр.1 Message(ad), dd ; our window? 
bne.s NextEvent 


btst80,d1 ; activate? 
beq.s Deactivate ; no 
move.] a2,-(sp) ; move Text Handle To Stack 
_TEActivate 
поуе.1 EditMHd1Ca52,-(sp) ; get handle to the menu 
move .w ®Undo! tem, -Csp) ; disable Ist item (undo) 
-DisableItem 

SetOurPort 
move.1 WindowHdlCa52,-Csp) 
—SetPort 


bra.s NextEvent 


; Deactivate window, turn off TextEdit, enable undo for the 
desk accessories. 


Deactivate 
поуе.1 a2,-(sp) ; get Text Handle 
—TeDeAct ivate 
поуе.1 EditMHd1(a5),-Csp) ; get handle to the menu 
move.w "UndoItem,-Csp)  ; enable Ist item (undo) 
-EnableItem 
; bra NextEvent ; *CAUTION!* if more code 
; is added after this routine, remember to uncomment the line 
above! 


Next Event 


NextEvent 
moveq 80,040 ; Say that it’s not Quit 
rts ; return to EventLoop 


: Window stuff 
ViewRect dc.w5,4,290,500; Text Record’s View Rect 
DestRect dc.w5,4,290,500; Text Record’s Dest Rect 
WBounds dc.w5,5,335,510 


j Event variables 

; IMPORTANT! remember, the EventRecord is 
; very much a variable and NOT a constant. 
; Never declare the EventRecord variables 
; with a dc command. 


EventRecordds .w 0 


What: ds.w1 ; event number 
Message: 05.11 
When: ds.11 


Point: 95.11  ; mouse coordinates 
Modify: ds.w1 ; key and button state 


;— Application variables 
AppleMHdl 945.11 ; handle for apple menu 
FileMHdl  ds.11 ; handle for file menu 
EditMHd] ds.1 1 ; handle for edit menu 
CmdMHd1 ds.11  ; handle for command menu 


aw awd аай  — 


DStorage | ds.wDWindLen 

DeskName | ds.w 16 ; DA name 

ItemHit ds.w 1 

WWindow ds.11 

WindowStorage ds .w WindowSize 

WindowHdl ds.11 ; handle to the window 
GSOffset ds.11 ; Get Scrap Offset dummy 
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¿Serial port variables 

IOBuf ds.b512 ; general I/0 buffer 

Outbuf 95.6512 ; sanitized version of IOBuf 
SerCon ds.wi ; current serial port conf ig 
BaudChk ds.w1  ; current checked item 
CharCnt 05.11  ; * of characters read 


end 
Listing: tera.r 


* This is the resource file for the program “Term” 
* the \CA character generates a “hard” space. 

* Give it a type APPL and creator FHMT. 

Term 

APPLFHMT 


* Get the code portion. 
INCLUDE term.code 
TYPE MENU 
‚1 
About Term... 


Command 
Erase screen 
(- 

1200 Baud 
2400 Baud 
9600 Baud 


Type DLOG 


2 


100 100 200 350 
Visible NoGoAway 
1 

0 

1 


Туре DITL 


ә 


2 


Button 
60 100 90 150 
OK 


StaticText 
15 40 59 238 
Simple Terminal Program\@D\CAFrank Henriquez 1/88 


TYPE WIND 

‚1 
Terminal 
44 7 337 507 
Visible GoAwau 
0 
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Assembly Lab 


Real-Time Driver 


A Real-Time Device Driver in MPW Asm 

When working in the laboratory or in engineering, it is often 
necessary to use the Mac to control serial devices. Such devices 
are generally configured to respond to simple commands, and 
provide a simple response. An example would be the American 
Edwards AccuPro™ Volumetric Infusion Pump, which is a de- 
vice for delivering intravenous infusions of drugs. This device 
contains an RS-232 interface, supports full duplex 2400 baud 
communication, and has a simple command language for setting 
and interrogating the device’s infusion rate, the limits for infused 
volume and infusion time, the volume already infused, and the 
status of the pump. 

Programming the pump involves four steps; the command 
string is built in memory, a pointer to this string is placed in a 
parameter block fora. PBWrite, a_PBRead is used to obtain the 
pump’s response, and the returned string is decoded. While this 
may seem simple, one must remember that the serial communi- 
cation takes a significant amount of time, and could take forever 
if the pump or the serial line fails. Additionally, the serial 
communications controller is capable of functioning with mini- 
mal CPU supervision, which transpires at interrupt level, and 
thus, it would be nice to use asynchronous device driver calls, to 
free the Mac to work on keeping the user interface going, while 
the serial controller handles the IO in the background. 

The program I will describe for performing these tasks is a 
driver. Most Mac programmers are familiar with drivers from 
writing DAs, however, a device driver is somewhat of a different 
animal, particularly when one wishes it to be “real-time” without 
intervention from the foreground program. The device driver has 
several purposes: 

1) To insulate the application from the peculiarities of the 
device, so that the device can be changed without requiring a 
change in the application. Additionally, the device could be 
simulated by a driver, so that debugging of application code can 
be done without having to have the physical device. 

2) Toinsulate the application programmer from having to 
understand how serial communications, real-time IO, etc. work. 

3) To permit all of the resources associated with the IO 
task to be grouped together, so that they can be installed and 
uninstalled easily. 

In writing such a driver, it is important to recall several 
important factors: 

1) Drivers cannot utilize application globals for their own 
storage. 

2) Drivers are only notified of events that pertain to them 
when they own the frontmost window, and then only receive 
mouse, keyboard, update, and activate events. 

3) Activities which occur at interrupt level (i.e. ioCom- 
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pletion routines, Vertical retrace tasks, Time manager tasks, etc.) 
are extremely limited in what they can do, due to the uncertainty 
of the heap. 

In order to write such a driver, several decisions were made: 

1) The driver utilizes applEvts to signal that it needed to 
regain control. Thus, the serial reads and writes utilize an 
ioCompletion routine which simply posts an app1Evt. 

2) Serial drivercalls havea time limit. When the serial call 
is queued (asynchronously), a Time manager task is primed. If 
the serial IO completed first, it stops the Time manager task from 
completing by setting the tmCount field to zero, and if the read 
or write did not complete within the specified time, the time 
manager task issues a _KillIO call on the relevant serial driver. 
This results in the ioCompletion routine being called, which 
notifies the driver. The time manager task is contained in a 
resource of type “TMMR’, which is loaded into the heap, locked, 
dereferenced, and the pointer placed in the tmAddr field of the 
time manager queue entry. The resource also contains a long- 
word of private storage, which holds a pointer to a private 
parameter block (used for the КІШО call). 

3) Applevtsare posted with the parameter block pointer of 
the completed serial call as the message. The pump driver places 
the parameter block pointer of the pending pump driver in the 
ioMisc field of the serial call parameter block so the downstream 
routines can keep track of it. Alternatively, the downstream 
routines could get this pointer from the dCtlQHead field of the 
DCE. 

4) ApplEvts are passed to the driver by a GetNextEvent 
filter. This routine is called at the end of the GetNextEvent trap, 
with Al pointing to the EventRecord, and boolean result in both 
DOandat4(A7) (See Macintosh Technical Note #85). If the what 
field of the EventRecord equals app1Evt, the routine examines 
the message, and if it contains a negative word in the ioRefNum 
field of the parameter block pointed to by the message, it 
processes the event. If the event is processed, the filter sets the 
boolean result to False, so the the application knows not to deal 
with it. In either case, the routine exits by a JMP to the previous 
contents of the JGNEFilter global. This pointer is stored locally 
in our GNEFilter proc. 

5) The GNEFilter is a separate resource (type = “GNEF’), 
which is loaded in the pump driver Open routine. The resource 
is patterned after the DRVR resource, in that it contains an offset 
to the code as its first word, and some local storage is provided 
between this word and the beginning of the code. The GNEFilter 
is loaded into the heap during the driver Open routine, using a 
_GetNamedResource call. This is done so that several drivers 
can share the GNEFilter, since only the first driver will load the 
resource into the heap. The GNEFilter keeps track of which 
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resources have opened it by keeping their reference numbers in 
the local storage. Duplicate entries are avoided. The GNEFilter 
also keeps a parameter block pointer in its private storage for its 
private use. 

6) When the GNEFilter processes an applEvt with a 
negative ioRefNum, it accesses the parameter block pointer in 
the ioMisc field of the parameter block referenced in the message 
field of the event, and checks to see that the ioRefNum of this PB 
is in the list of cooperating drivers in the GNEFilter private 
storage. If it is, then we place the event pointer in the csParam 
field of the GNEFilter's private parameter block, set the csCode 
to accEvent, and the ioRefNum to reference number of the 
ioMisc parameter block (this will be the ioRefNum of our driver; 
the ioRefNum of the parameter block passed in the message field 
will be one of the serial drivers). We then issue an immediate 
. Control call. 

7) The Control routine supports four csCodes — accEvent, 
accRun, KillIO, and GoodBye. Goodbye simply JMPs to the 
Close routine. KillIO issues KillIO calls on the serial drivers and 
returns. AccRun asynchronously queues a Status call on the 
driver to inquire the pump status (thus, irrespective of what the 
application does, it will be notified of the pump status periodi- 
cally). The accEvent csCode is generated by our GNEFilter, and 
is used to allow the driver to respond to serial IO completion at 
event level (that is, when the heap is consistent). The routine 
examines the low nibble of the ioTrap field of the parameter 
block pointed to by the event message. If the trap was. Write, the 
routine sets up the parameter block for single character rcads on 
the serial input channel and queues an asynchronous | Read. If 
the trap was, Read, the routine examines the character read. If 
the character is a carriage return (ASCII 13), the accumulated 
input buffer is sent to be digested, if it is an asterisk (*), it is 
ignored (the McGaw pump generates these periodically to let us 
know it is pumping), and if itis any other character, it is appended 
to the input buffer. In the latter two cases, the routine queues 
another asynchronous Read. In the first case, the routine posts 
anapp2Evt with the message the pointer to the original parameter 
block used to queue the status call, and exits via JIODone. 

8) The Status routine uses the three words in the csParam 
field of the parameter block to figure out what the application 
wants the driver to send to the pump. The Request field is used 
to look up a single character in a table (which is loaded from a 
resource of type 'PDDF"). This character specifies which of the 
pump functions is to be interrogated or set, as specified in the 
Action field. The Info field contains the numeric value to be 
passed to the pump and/or returned to the application. The pump 
in general wants decimal integers, but in some cases wants a hex 
word, and the formatting information is specified in the table. 
Having constructed the string to be sent to the pump, the routine 
allocates a parameter block, places the string pointer in the 
ioBuffer field, the pointer to the driver Status parameter block in 
the ioMisc field, fills in the ioCompletion address, and queues an 
asynchronous Write. Note that if the noQueucBit of the trap is 
set, the Status routine places the request at the head of the queue. 
It does this by checking the queue, and if there are zero or one 
queue entries, issuing the Status call asynchronously, but if 
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there are two or more queue entries, it slips the request after the 
current queue head by changing the qLink fields of the qHead PB 
and the PB in question. 

9) The Open routine loads the GNEFilter and time man- 
ager task (as detailed above), opens the serial drivers and config- 
ures them for the pump, loads the pump request table, allocates 
the dCtlStorage handle, and sets up the driver globals there. 

10) The Close routine removes the time manager task, 
closes the serial ports, removes the driver's reference number 
from the GNEFilter private storage, and restores the previous 
GNEFilter if it is the last value there. It then deallocates all the 
pointers and handles it allocated and exits. 

The application thus needs only do the following things to 
utilize the driver: 

1) Open the driver 

2) Allocate a pointer for the parameter block, setting the 
three words in the csParam field to pass the desired function, and 
queue the | Control call. The call should be made asynchro- 
nously. Immediate calls can be used to “jump the line", that is, 
make sure the call is the next one to be taken from the queue. 

3) The event loop should handle app2Evts by first process- 
ing the information in the ioResult and csParam fields, then 
disposing of the pointer. 

4) Ifthe pump driver is to function irrespective of what the 
application is doing, the application must frequently call  Get- 
NextEvent with the event mask applEvt mask set. In order to 
guarantee this you will need a FilterProc for ModalDialogs and 
Alerts which calls _GetNextEvent with the event mask set to 
applMask when the routine receives a null event, and a 
DragHook and MenuHook which calls GetNextEvent with the 
event mask set to appl Mask. Additionally, any compute-inten- 
sive routines might include a call to the DragHook routine. The 
alternative is to keep track of driver calls and repost the ones that 
time out. 

5) Call SystemTask if you want periodic events. 

6) Prior to closing the driver, you should do one of two 
things: 

a) Issue a КІШО call on the driver to flush the queue. 

b) Waituntil the queue empties itself. This can be done by 
waiting until the dCtlQHead field of the driver's DCE is zero. 

This is necessary because the Close trap sits and waits 
for the driver to complete the pending request. The driver cannot 
complete the request, however, without the event loop, so we 
hang forever. 

7) While the driver is set up to handle goodbye kisses to 
close the structures, itis much safer to close the driver explicitly, 
due to the serious adverse consequences of exiting without 
restoring the JGNEFilter pointer. The truly paranoid can load the 
GNEFilter into the system heap. The same caveat applies to the 
time manager queue entry (the pointer, not the routine) — if this 
is deallocated but not removed from the time manager queue, bad 
stuff will happen. I have not extensively worked on making the 
driver "safe as milk", in general, during debugging, if it crashed, 
I rebooted. But then, I just got my Mac II. 

8) Theprogramis written in MPW assembler, and uses the 
structured programming macros. I have hacked up some of these 
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to make them work properly for writing drivers. The only | * Load the peii request table from the 
significant change is in DRVRExit, which checks the noQueue- [eser ees ron 


Bitof the argument, and if it is clear, exits via the JIODone vector, Call _GetNamedResource:L (#/PDDF’:L, #/Table’:A 
otherwise, RTS. ), A4:L 
The code for the driver, the GNEFilter, and the timer task, as pa ck ORAS 
well as the rez files and the shell commands to build the driver are -GetHandleSize 
presented below. Note that I actually build the driver as a desk If? 00 ii е 
accessory. This is done so that I can install it with the DA Mover. 2. аны а 
This is easier during development, but once the driver is de- EndIf 
bugged, it can be changed with the resource editor. EXG А@,А4 


MOVE.L 00,01 


The sources have been hacked for the sake of brevity. All MOVE L A@,-CSP) 


INCLUDES were deleted, many equates omitted, and code 
specific to the pump deleted as well. If you really want to | * Get a new handle to put the Driver 


assemble this, get the source disk. globals and the pump request table into 
TITLE “Pump driver’ 
ParamBlockSize equ 108 


% 


MOVE.L A1,-(SP) 
ADD.L fiTebleOffset,D0 


ActionOffset equ csParam _NewHandle clear 
RequestOffset ^ еди csParam+2 " HLock | 
InfoOffset equ сѕРагат+4 


MOVE.L A2,dCtlStorage(A2) 


MOVE.L CAG) Al 
Enab ledF lags еди (i««dStatEnable) Y MOVE.L A1,A3 


+ CI««aCtlEnable) + €1<<dNeedT ime) ADD.L *TableOffset,A1 
MOVE.L CResHandle), Ad 


EventMask equ 1<<app 1Еу{ MOVE.L 01,00 
-BlockMove 
DStore | Record 0 Call  .ReleaseResource С ResHandle:L) 
WriteUnit DSW 1 MOVE.L CSP)+.Al 
ReadUnit DS.W 1 i 
"y is^ i l i * Open the serial drivers and set them up 
b i D I * for the pump (I have ommitted the .AIN code 
ee SL 1 * since it is identical 
IncomingLength — DS.B 1 
IncomingString DS.B 9 MOVE .L *ParamBlockSize,D£ 
Align 2 -NewPtr ,clear 
TableOffset equ * LEA 8” AQUT’,A2 
Баш DS.W 1 MOVE.L A2,ioNamePtr(A0) 
Table DS.W5 MOVE.B #fsWrPerm,ioPermssn(A0) 
ENDR _Open 
| If* 00 NE.W #noE Then. 
IO0String Record 0 MOVE.L ру vi : 
OutgoingString DS.B 8 MOVE.W #openErr , ioResultCAg) 
ReadBuf f er DS.B 1 Return 
| А11дп 2 EndIf” 
StringAllocation equ  * MOVE.W ioRefNumCA0), 
ENDR WriteUnitCA3) 
DRVRStart DRVREntry * Set the output port for 2400 baud, 1 
x i ight bi icatio 
DRVRBegin Save=A2-A4/D1-D2, \ stop, no parity, eight bit communication 


withz(DStore, IOString, GNEGlobals); MOVE .W 'PortSetting,csParamCAQ) 


MOVE .W #8 csCode(Ad) 


DC.B Enab ledF lags 

DC.B 0 -Control 
DC.W 17560 ; T seconds I А 
DC.W EventMask -DisposPtr 
DCW 0 ; No menu 


Set up a parameter block for the serial 
IO timeout function. The pointer is 
stored in the Driver private storage. 
Insert task into the time manager queue 
which performs the IO timeout function. 


DC.W DRVROpen 
DC.W  DRVRPrime 
DC.W DRVRControl 
DC.W DRVRStatus 
DC.W  DRVRClose 


и + и и и 


MOVE.L ttParamBlockSize,D0 
| -NewPtr ,clear 
DRVRTi tle n" MOVE.L AQ, KillBlock(A3) 
DC.B X 'PumpDriver MOVE.L #1588, TimeCount (A3) 
ALIGN 2 MOVE.L ®tmQSize, DO 
_NewPtr 
DRVROpen DRVREnter MOVE.L AQ,KillTaskCA3) 
MOVE.L A1,A2 Call TimeOutInstall C A0:L , 
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KillBlock(A3):L ) 
* Install the GNEFilter 


Call _GetNamedResource:L С ®’GNEF?’:L 
, "'GNEFilter ":A ),A2 


CMPA #9, A2 
Ift МЕ Then.S 
MOVE.L (A2),A2 
MOVE .W Drvr_num(A2),D1 


Ift 01 EQ.W 80Тһеп.5 
MOVE.W СА2),00 
LEA (A2,D0.W),A3 
MOVE.L JGNEFilter,-4CA3) 
MOVE.L A3,JGNEFilter 
MOVE.L — *"IParamBlockSize,DO 
-NewPtr ,clear 
MOVE.L Аб, Control. Ptr(A2) 


EndIft 
MOVE.W dCtIRefNumCA 12,02 
If" 01 LE #entru-slots Then.S 


Fort D1 DownTo #1 Do.S 
If* Drvr numCA2,D1.W*2) EQ.W 
D2 Then.S 


Golo#.S DuplicateDrvr 


EndIf# 
EndF® 
ADD .W 8$ 1, Drvr.numCA2) 
MOVE.W  Drvr-numCA22,01 
MOVE.W D2, 
Drvr_num(A2,D1.W*2) 
Е15е&.5 


х Get the Resource ID for the driver to 
* calculate the ID of owned Alert 


* (sub ID 0) 
LEA DRVREntry, Ай 
-RecoverHandle 
LINK A6, 8-12 
Call -GetResInfo С Аб: , CA6):A , 


4€A6):A , 8CA6):L ) 
MOVE.W (A6),D2 
UNLK A6 
MULU 832,02 
ADD.W *$0wned,D2 
Call —CautionAlert:W С D2:W , 
Ø:L ),CC 
EndIf® 
EndIf® 
DuplicateDrvr : 
MOVE.L CSP)+, Ад 
MOVE .W ЗорепЕгг, ioResultCA2) 
Return 


DRVRClose DRVREnter 
MOVE.L A®,-CSP) 
MOVE.L dCtlStorageCA1)2,A2 
MOVE.L (A2),A3 


MOVE.L ЗРагатВ1осК5і2е,00 

-NewPtr ,clear 

MOVE.W ReadUnitCA3), ioRef NumCA2) 

Close 

MOVE .W WriteUnitCA3), 
ioRefNum(A0) 

_Close 

_DisposP tr 


MOVE.L KillTaskCA3), A 
-RnvTime 

-DisposPtr 

MOVE.L KillBlockCA32,A0 
-DisposPtr 
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Move.L А2,А0 
-DisposHandle 


MOVE.W dCtRefNumCA 12,02 
Call  .GetNamedResource:L € 
8^GNEF^:L , #“GNEFilter :A 2,42 


CMPA m0,A2 
Ift МЕ Then.S 
MOVE.L СА2),АЗ 
MOVE.W Drvr_num(A3),D1 


If? 01 GT.W #1Then.S 
While® D2 NE.W 
Drvr.numCAS,D1.W*2) Do.S 
DBEQ.W D1,DuplicateClose 


Endw® 
If 01 NE.W Orvr_numCA3) Then.S 
ADD.W 81/01 
Рог“ D1To Drvr_num(A3) 
Do.S 
LEA Drvr.numCA3,D1.W*2), 
A4 
MOVE.W (А4),-2(А4) 
EndF® 
EndIf! 
SUBQ.W #1, Drvr_num(A3) 
Elself#.S 01 EQ.W #1 Then.S 
Ift 02 NE.W DrvrentriesCA3) 
Then.S 
GoTo®.S DuplicateClose 
EndIf! 
MOVE.L GNE_Next(A3), 
JGNEF i l ter 
Call _ReleaseResource С A2:L ) 
EndIf# 
EndIf# 
DuplicateClose: 
MOVE.W ®noErr , DØ 
MOVE.L (ӨР), Ad 
DRVRExit ioTrepCA2) 
DRVRPr ime DRVREnter 
MOVE .W поЕгг,00 
Return 
DRVRStatus DRVREnter 
* First, check to see if this is an 
* immediate call. If so, it “jumps the 
х line”, and will be the next call serviced 
* after the current one Cif anu) is 
x 


comp leted. 


MOVE.W іоТгар(А0),01 
BIST #noQueueBit,D1 


If" NE Then.S ; Immediate call 

LEA dCtlQ0Head(A12,A2 

CMP.L 80 (A2) 

If EQ Then.S ;queue empty 
-Status ,async 
Return 

EndIf”? 

MOVE.L (A2),D1 

CMP .L 4(А22,01 


If® EQ Then.S; only one entry 
-Status ,async 
Return 

EndIf# 


* Fool the driver into thinking this is an 
* asynchronous queue entry 


MOVE.W іоТгар(А02,01 
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зе © э ж 


3 x ж * 


3 x * ж 


DRVRContro]l 


x © ж м 


BCLR QinoQueueBit,D1 
BSET tasyncTrpBit,D1 
MOVE .W 01, ioTrapCA0) 

MOVE .W #1, joResul tC Ad) 


Get parameter block of queue head, put 
qLink of qHead in current parameter 
block;and replace it with current 
parameter block pointer 


MOVE.L (А2),А2 
MOVE.L (A2),CA0) 
MOVE.L Ай,(А2) 
Return 

EndIf” 


MOVE.L AQ, А2 
MOVE.L dCtlStorage(A 1), А4 
MOVE.L (А42,А4 


MOVE.W TableLenCA42,D1 
MOVE.W RequestOf fsetCA2), DØ 
If" DØ GT.W D1 Then.S ;Not a valid 


MOVE .W *statusErr, ioResult(A2) 
MOVE.L А2,00 
MOVE.W tapp2Evt,A0 
-PostEvent 
MOVE.L A2,A0 
MOVE.L "istatusErr , D 
DRVRExit ioTrapCA2) 
EndIf# 


MOVE .L "ParamBlockSize,D 
-NewPtr ,clear 


The next section of code places a pointer 
to the needed string, and the number of 
characters, into the parameter block. It 
was ommitted from this listing. 


MOVE.W WriteUnitCA4), 

ioRefNumC AB) 
LEA SerialComplete, АЗ 
MOVE.L АЗ, ioCompletionCA2) 
Write ,async 


Set up the time manager task to К11110 
on the channel in TimeCount 
milliseconds. KillBlock is a previously 
allocated parameter block. 


MOVE.L KillBlockCA4)2,A0 

MOVE.L WriteUnitCA4), 
ioRefNumCA2) 

MOVE.L Kill TaskCA4), Ad 

MOVE.L TimeCountCA4),D0 

PrimeTime 

MOVE .L ®noErr , DØ 

Return 


DRVREnter 


ИВ csCodeCA®) EQ.W #accEvent 
MOVE.L csParamCA2), A2 
MOVE.L message(A2),A2 
MOVE .W ioTrapCA2),D2 
AND . W 8%00ҒҒ,02 
MOVE.W ioResu1tCA22,D3 


Check to see the serial call was not 
aborted by KillIO. If so, inform the 
application, dequeue the pump driver 
call, and return 
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¿pump call 


Then 


% x 2 м 


* % * и жи и ммм 


If® D3 EQ.W #abortErr Then.S 
MOVE.L ioMiscCA2), Ad 
EXG AG, A2 
_DisposPtr 
MOVE.W TimeOut, ioResultCA2) 
ADD .W D2, ioResult(A2) 
MOVE.L — A2,D0 
MOVE.W app2Evt, Ad 
-PostEvent 
MOVE.L — "TimeOut,D0 
MOVE.L — A2,40 
DRVRExit ioTrəap(A0) 

Елді 
Тһе serial call did not time out, so 
figure out if it was a READ or a WRITE 
bu examining the low nubble of the trap 
field of the parameter block. 

Ift 02 EQ.W #aRdCmd Then 
READ - examine the character read. If it 
is a ‘*’, we ignore it and queue another 
read. If it is a carriage return, we call 
RespondToRead to interpret the 
completed pump response. Any other 
character is incorporated into the string 
being built at IncomingString and we 
increment the IncomingLength byte, 
then queue another READ. If we exceed 
8 characters, we have а problem. 

MOVE.L ioBufferCA2),A3 

MOVE.B САЗ),01 

MOVE.L dCtlStorage(A1),A4 

MOVE.L (A4),A4 

[ГВ D1EQ.B #13 Then.S 
MOVE.L KillTask(A4),A0 
CLR.L tmCount(A0) 


MOVE.L ioMisc(A2),A3 
CallRespondToRead 
MOVE.L ioMisc(A2),A0 
EXG A0,A2 
-DisposPtr 
MOVE.L А2,00 
MOVE.W 'app2Evt, Ad 
-PostEvent 
CLR.B IncomingLength(CA4) 
CLR.L IncomingStringCA4) 
CLR.L IncomingString*4CA4) 
CLR.L DØ 
MOVE.L А2,А0 
DRVREx it 
ElseIf*.S 01 EQ.B 4%” 
MOVE.L А2,А0 
-Read ,asunc 
Return 
Else#.S 
MOVE.B IncomingLength(A4), 


ioTrapCA2) 
Then.S 


IncomingString(A4,D0.W) 
ADD.W 81,00 
If® 00 LE.W 

MOVE.B 00, 
IncomingLengthCA4) 


88 Then.S 


Else®.§ 
MOVE.L Kil1Block, Ad 
MOVE .W ReadUnit(A4), 
ioRefNumC AB) 
-KilllO 
MOVE.L ioMiscCA22,A0 
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EXG A0,A2 RetAddr D$.L 1 


-DisposPtr A6L ink DS.L 1 
MOVE.L A2,D0 LocalS ize equ * 
MOVE .W #app2Evt,A0 ENDR 
-PostEvent 
MOVE.L А2,А0 MAIN 
MOVE.L WITH EventRecord,StackFrame 
®TooManyCharacters, 00 ,GNEGlobals 
DRVRExit ioTrap(A0) 
EndIf# Entry ОС." GNEFilter ;Offset to 
MOVE .L A2, A ‚СМЕ filter 
-Read , async DCB .B GNEG lobalSize,@ 
Return 
EndIf# GNEF ilter: 
ElseIf?*.S 02 EQ.W ttaWwrCmd Then.S 
MOVE.L dCtlStorage(A1),A4 х If the event is not an applEvt, go to the 
MOVE.L СА4),А4 * next event in the GNE filter chain, 
MOVE.L  KillBlockCA42,A0 Ж which we previously stored in GNE Next 
MOVE.W — ReadUnitCA4), 
ioRefNumCA2) LEA Entry, Ad 
MOVE.L — A2,A0 CMP.W #applEvt,what(A1) 
MOVE.W ReadUnitCA4), BNE.S Out 
ioRefNum(A0) 
MOVE.L #1,ioReqCount(A0) х We have an appiEvt. Check to see if the 
MOVE.L ioBufferCA®), А2 х ioRefnum is negative. 
LEA ReadBuf fer (A25,A2 
MOVE.L А2 ioBufferCAQ) LINK A6,#LocalSize 
LEA SerialComplete,A4 MOVEM.L A2/D1-D2, -CSP) 
MOVE.L — A4, ioCompletionCA2) MOVE.L messageCA1),A2 
-Read ,async MOVE.L ioMisc(A2),A2 
Return MOVE.W ioRefNumCA22,D1 
EndIft If" GE Then.S 
Elself#.S csCodeCA®) EQ.W ttaccRun 60108,5 PreOut 
Тһеп.5 EndIf# 
MOVE.L A0,-CSP) 
MOVE.L *ParamBlockSize,D@ * We have a negative ioRefnum. Check to 
-NewPtr ,clear * see if it is in the list of ioRefnums 
MOVE .W dCtlRefNumCA 1), * we are cooperating with. If it is, pass 
ioRefNumCA) * the event to the driver by setting 
MOVE .W 85 request, * up & parameter block for an immediate 
RequestOf f setCA2) * call to the control routine. 
MOVE.W 8Ask ActionOffsetCAQ) 
CLR.L ioCompletionCA2) MOVE.L Control. PtrCA02,A2 
-Status ,async LEA Drvr.numCA2), AQ 
MOVE.L (SP )+, A MOVE.W CA®)+,D2 
ElseIf*.S csCodeCA®) EQ.W #killCode Loop: 
Then.s For® D2 DownTo #1 00.5 
MOVE.L 8ParamBlockSize,D0 MOVE.W (A0)*,D0 
MOVE.L dCtlStorage(CA12,A2 If* 00 EQ.WD1Then.S 
MOVE.L (А2), А2 MOVE.W 01, ioRefNumCA2) 
-NewPtr ,clear MOVE.W %accEvent, сѕСодеСА2) 
MOVE .W ReadUnit(A2), MOVE.L А1,с5Рагат(А2) 
ioRefNumCAQ ) MOVE.L — A2,A0 
-К11110 Control , immed 
MOVE .W WriteUnitCA2), CLR.W 00 
ioRefNum(A0) MOVE.N D0,Result(A6) 
-К11110 Leave®.S Loop 
-DisposPtr EndIf# 
Return EndF8 
Elself8.S csCodeCAQ) EQ.W #goodBue PreQut: 
Then.S MOVEM.L (SP2*,A2/D1-D2 
JMP DRVRClose UNLK A6 
EndIf” LEA Entry, AQ 
Out: 
MOVE.L #noErr,D0 MOVE .L GNE_NextCA®), Ad 
DRVRExit ioTrap(A0) JMP (AQ) 
ENDP ENDP 
END END 
The following is the GNEFilter Code: The following is the timeout task: 
TITLE ‘GNE filter’ TITLE ‘Timeout for serial IO" 
StackFrame RECORD (A6L ink) , DECR Main 
Result DS.W 1 
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KillStore DC.L 0 
KillRoutine: 

LEA KillStore,A0 

MOVE.L CA02,A0 

-KillIO 

RTS 

ENDP 

END 


The following contains the timeout routine installtation, and the 


serial ioCompletion routine 
TITLE 'Timeout for serial IO" 


Export Procedure TimeOutInstall 
C KillTask:L , KillPtr:L 2 
Begin Save-A0-A2 


Call _GetNamedResource:L 
C 8^TMMR^:L , ®’KillRoutine’:A 2,A1 


CMPA &0,А1 

[fs NE Then.S 
MOVE.L (A15,A1 
MOVE.L KillTaskCFP),A0 
MOVE.L KillPtrCFP2,CA1) 
LEA 4(A1),A1 
MOVE.L A1, tmAddr CA0) 
_InsTime 

Елді” 

Return 

ENDP 


* Serial Complete - This routine is the 
Ж ioCompletion routine for the 


* asunchronouslu serial IO calls from the 
* pump driver. On completion, the routine 
Ж posts ап applEvt with the message the 
* parameter block of the completed serial 
* call. 
Export Procedure SerialComplete 

Begin Save=A5 


MOVE.L CurrentA5,A5 
MOVE.L A0,D0 

MOVE.W #app!Evt,A0 
_PostEvent 

Return 

ENDP 

END 


The following are the shell commands to build this as a desk 


accessory and install it with the DA mover. 
Asm TimeOut.a 
Asm KillRoutine.a 
linkKillRoutine.a.o à 
-о PumpDriver -ra KillRoutinez16 д 
-sn 'Main-KillRoutine^ à 
-rt TMMR-- 15296 
Asm GNEFilter.a 
link GNEFilter.a.o à 
-o PumpDriver -sn ‘Main=GNEFilter’ à 
-ra GNEFilter=16 -rt GNEF=- 15296 
Asm Pdriver.a 
link Pdriver.a.o TimeOut.a.o -t DFIL à 
-c DMOV -o PumpÜriver -da à 
-sn ‘Main=PumpDriver’ -rt DRVR=34 
"HD 48:System Folder:Font/DA Mover” д 
PumpDriver test drvr 27 
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Assembly Lab 


Assembly Language 
jor the Rest of Us 


Introduction and Purpose 

I’ve always found thatit’s the little things in life that hang me 
up. The grandiose projects somehow seem to fall in place, but 
when I want to doa simple project, using only obvious facts, I find 
that those facts must be so obvious, no one has bothered to write 
them down. 

Most people who program do so to create little tools. As an 
engineer or scientist might we write our code in a high level 
language like Pascal, C, Fortran, or LISP in order to efficiently 
read and debug our code (especially with tools from people like 
Think Technologies and Coral Software). Once the code is up 
and running, we may notice that one of our procedures, lets say 
one that crunches a lot of numbers using SANE, is taking up 
most of the processing time. By rewriting this one part of the 
program we can speed things up dramatically, often 10 times or 
more! 

This article is about assembly language. It’s not about 
writing a lightening fast game or anew version of Excel™ , rather 
it’s about using the minimum amount of programing we can get 
away with in order to write a short but useful little bit of code. 
Neither is it about writing a stand alone program in assembly, but 
instead we will take a program written in Pascal and rewrite just 
one of it'S procedures in assembly language, so the entire 
program can run much faster. 


What we will do 

In this article will recode a small subroutine whose mission 
in life is to take an array and multiply each of it's elements by a 
scalar constant. Although the program is not the most dramatic 
use of assembly language, and the code we write will not be the 
most elegant, hopefully it will be clear and easy to understand". 
We will be illustrating the steps needed to interface any code with 
a running Pascal program. I chose to make use of the 68881 
floating point processor? in our program, not to add complexity, 
but to illustrate how easy it is to use this chip. Motorola has made 
the 68881 appear simply to be an extension of the 68000 CPU*. 
To the programmer the combination of a 68000 and a 68881 
appear as a souped up 68000, just like the basic version but 
turbocharged for numeric speed with a few more instructions and 
registers added to it. If you don't have this chip the same 
principles of programing apply. You would simply replace the 
68881 instructions with a few more 68000 instructions, but the 
programing logic would be the same. 


MPW Assembler, LSP, and MDS 
I will be using LightSpeed Pascal® to develop our main 
Pascal program. As I explained above the basic program creates 
an array, then multiplies each number within the array by a 
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constant. LightSpeed is a great product for writing quick and 
dirty programs, since you can debug and observe your variables 
as you go. Iteven has an assembly level debugger built right in, 
So if you want to peek at the actual memory to see exactly what 
your instructions are doing, you can. This is a great way to learn 
the simple and predictable way each line in your program will 
effect memory. 

We will also be using Macsbug™ , a source level debugger 
that should be available either from your local computer dealer, 
most user groups, bulletin boards, and/or commercial language 
products (including LightSpeed). With Macsbug we can look at 
everything the Mac is doing, while it follows our assembly 
language instructions as they execute, oneline atatime. Tracing 
our code as it executes will make it clear that each instruction has 
very predictable and simple results (Remember that if a com- 
pressed piece of sand called the 68000 can understand what these 
instructions mean, so can you!). 

Finally we will be using the assembler built into the MPW 
shell? (version 2.02). Consulair also makes a stand alone Assem- 
bler that was the standard of the industry’. 

In this article we will assume? that you know a what a bit is 
(Oor 1), that 8 bits are stored ina byte, that 16 bits make up aword, 
and finally that 32 bits make up a long word?. We also assume 
that have some idea of what a hexadecimal number is!?, 


The Pascal Code 
First lets take a look at the Pascal Code: 


PROGRAM TestSM; 
USES 
SANE ; 
TYPE 
element = PACKED RECORD 
empty : integer; 
n : extended; 
END; 
vector = ARRAYI2..19] OF element; 
matrix = RECORD 
rows : integer; 
columns : integer; 
vecPtr : ^vector 
END; 


VAR 
inVect : vector; 
outVect : vector; 
i : integer; 
inMatrix, outMatrix 
scalar : extended; 
error : integer; 


: matrix; 


FUNCTION ScaleMult Cscalar 
inMat, outMat : matrix) : 
external; 


: extended; VAR 
integer; 
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BEGIN 

ShowText; 
scalar := 35; 
inMatrix.rows := 0; 
inMatrix.columns := 19; 
inMatrix.VecPtr :- @inVect; 
outMatrix.rows := 0; 
outMatrix.columns := 19; 
outMatrix.VecPtr := @outVect; 
writelnC'scalar = ', scalar); 
writelnC‘’scalar, inMatrix, outMatrix, error, inVect’); 
writeClongint(@scalar), longint(@inMatrix), 
longintCéoutMatrix2, longint(@error 22; 
writelnClongintC8inVect2); 
FOR i := 0 TO 19 DO 

BEGIN 

inVect[il.empty := 255; 
invectlil.n := i; 

END; 
error := ScaleMultCscalar, inMatrix, outWatrix); 
writelnC'error = ', error); 
writeln(’i’:5, ’inVect’: 10, ‘outVect’: 10); 
FOR i := Ø TO 19 DO 

writelnCi:5, inVect[il.n:10, outVect[i].n:10); 
writelnC'scalar = ', scalar); 
writelnC'The End... ^); 


END. 


In this article, we will rewrite the function ScaleMult in 
assembly language. From our perspective, all that Pascal does is 
hand ourassembly language program the information in the form 
we declared in the interface statement. Since we have declared 
our subroutine as a function, our responsibility will be to return 
a result to Pascal, also in the form we declared. Pascal does not 
care how we perform our task, only that we get it done. 

The first unusual item that you may notice is our definition 
of an element. In most programming, numbers with decimal 
places in them are defined as "real" numbers. An example of a 
real number would be 3.14159 or “3.14159 E40". The last part, 
"E40" means that we will multiply our number “3.14159” times 
tenraised to the the zero power (which is equal to one). We could 
have simply written the number as 3.14159 and Pascal would 
have interpreted it the same way. If the number contained “E+1' 
then we would have multiplied our base number by ten raised to 
the first power (or 10), or we could have written the equivalent 
real number as 31.4159. Similarly "E43" would have meant 
multiplying by 10? (or 1000) and been equivalent to 3,141.59. 
SANE uses a more accurate form of the real number, called an 
extended number. The extended format can hold more decimal 
placesthanareal number, and itcan also raise a number toa larger 
power than a real number (a real number can run between 
+3.4Е+38 and +1.2E-38, whereas extended numbers can (ар- 
proximately) extend from +1.1E+4932 and +1.7E-4932, with 
more decimal places stored for each number). All of those extra 
decimal places translate into more accuracy as we do our calcu- 
lations. 


In our program we have defined an element to be: 
element = PACKED RECORD 


empty : integer; 
n : extended; 
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END; 


Instead of just holding an extended number, our element has 
an integer (which is empty) placed in front of it. We have done 
this to provide for the difference between the way SANE and the 
68881 handle extended numbers. Although we will explain the 
reasoning below (it's actually not hard to understand), for now 
simply consider each Element of the array as an extended Format 
number. 


Basic Assembly Language 
Now lets take a look at our assembly language function: 


MC6888 1 ; We will be using 
; instructions for 


; the 68881 chip 
MACHINE МС68020 ; optimize for the 
; 68020, if you don't 
; have one remove 
; this line 


ScaleMult FUNC EXPORT 
; this lets the rest 
; of the world know 
; about our function 


Debugger OPWORD $A9FF 

; into Macs bugs so 
we can follow every 
instruction and 
observe the 
registers 


; this will pop us 


we We o 899 We 


; The following are all displacements so we 
; can address our data on the stack, relative 
; to the address stored in A6 


result EQU 20 ; two bytes for our 
; integer result 
Scalar EQU 16 ; 4 bytes (address of 
; the scalar) 
inMat EQU 12 ; 4 bytes Caddress of 
; the input Matrix) 
outMat EQU 8 
; 4 bytes (address of 
; the output Matrix) 
ReturnAdd EQU 4 ; 4 butes 
superScalar EQU -12 
; 12 bytes (hold a 
; place for our 68881 
; version of the 
; scalar) 
o1dA2 EQU -14 ; Old the old value 
; Of A2 
o1dA3 EQU -16 ; old the old value 
;of АЗ 


X** Add the following features (to make 
this a “real” program): 
1) make sure the number of 
rows and columns in the input ; 
hat of the ; the output matrix. 
; 2) Fix the error message to 
tell the Pascal Program if 
there was a problem, such as 
if: rows X columns # vector 
size 


Matrix jives with 


c=... MM 


"o. `w. 0 0 


; ***** The first “real” line of our program ; 
Cit’s about time!) 
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we We `. We 


wee We We We We We We 


%“ е We We We We We We We We We We We `. `. We 


wee ` 


Debugger ; jump into Macsbugs 
; SO we can follow 
; what's going on 


move all the initial parameters off the 
Stack from the calling routine "function 
ScaleMult C(scalar:extended;var inMatrix, 
outMatrix:matrix) :еггог” 


link Аб, 8-12 ; push Аб (the frame 
; pointer) onto the 

stack , load SP 

into A6, then 

subtract off 12 

bytes from A7 to 

make room for our 

variables 


we We We We We We Dw 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


after the link instruction 
the stack looks as follows: 


high 
integer (2 butes) 
<- 20(A6) 
scalar (4 bytes) 
«- 16(A6) 
inMatrix (4 bytes) 
«- 12(А6) 
oldMatrix (4 bytes) 
«- 8(A6) 
returnAddress (4 bytes) 
«-  4(A6) 
old A6 (4 bytes) 
‹- (Аб) 
superscalar (12 bytes) 
<- -12(А6) 
and initial (А7) 
low 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


; now move the addresses onto the chip so we 


can work with them 
MOVE.L A2,-CA7); push A2 onto the 
; Stack to save it 
АЗ,-САТ); do the same to АЗ 
inMatCA6), А2 
; get the pointer to 
; the address of 
; inMatrix 
4(A22,A0 ; get the address of 
; the input matrix 
; (4 bytes from the 
; Stert of our matrix 
; data structure ) 
outMatCA6), A2 
4(А22,А1; get the address of 
; the output matrix 
inMat(A6),A2 ; get the number of 
; rows (first bute of 
; Matrix record) 
(A2),D0 
2(A2),D1; then get the number 
; Of columns (3rd 
; bute of matrix 
; record 


MOVE.L 
MOVE.L 


MOVE.L 


MOVE.L 
MOVE.L 


MOVE.L 


MOVE .W 
MOVE .W 


MOVE.L scalarCA6),A2 
; we will now move 
; the scalar to a 


; place with a bit 


40 


LEA 
CLR.W 
MOVE.L 


MOVE .L 


MOVE .W 


LEA 
MOVE .L 


LSL.L 
LSL.L 
MOVE.L 


FMOVE.X 


Loop 


2 


LSL.L 
LSL.L 
MOVE.L 
FMOVE .X 
FMUL .X 
FMOVE.X 


MOVE.L 


LSR.L 
LSR.L 
MOVE.L 
MOVE.L 


LSR.L 
LSR.L 
MOVE.L 


ADD 


ADD 
DBLT 


> column 


MOVE.L 
MOVE .W 


DBLT 


; more room 
superScalar(A6),A3 
САЗ )+ 
СА2)+, CA32* ; move the first 4 
; butes 


СА2 )+, САЗ)+; move the next 4 
; bytes 


СА2), САЗ); move the last byte 


superScalar(A6),A2 
(A22,D2 ; get the top 
; long-word of 
; the scalar, shift 
; it, then put it 
; back 
88 02 
#8 02 
D2, (A2) 


(A2),FP1; get the modif ied 
; scalar and store it 
; on the 68881 


MOVE.L (A0),D2 ; get the current 
; high Long word of 
; the element from 
; the input matrix 

88 D2 

88/02 

D2, CAB) 


(A0),FP0; get the current 
; element 
FP 1,ҒР0 
; scalar 
FPØ, CA1) ; put the element 
; back in RAM 
(А12,02 ; now shift the high 
; Long word back (in 
; the output 
; matrix,and then put 
; it away in RAM 
#8 D2 
88 02 
02,(А1) 
(А0),02 ; now shift the high 
; Long word back (in 
; the input matrix) 
; and then put it 
; away 
#8,D2 
#8,D2 
D2, CAB) 


; multiply by the 


512, A0 ; increment the 
; element’s address 
; Cto get the next 
; element) 

812,A1 


D1,Loop ; decrement the 
; Number of columns 
; and test 


; if we are here we have gone through one 


inMatCA6), А2 

2(А22,01; restore the number 
; Of columns 

DØ, Loop ; test if we have 
; completed through 
; all the rows 


; if we are here, we have gone through all 
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the rows 


we 


Since we have done our work let’s put away 
our toys (clear the stack of all the 
garbage) and go home. 


we We 


Wwe 


MOVE.L (CA7)+,A3 ; pop off the old A3 
MOVE.L (CA7)+,A2 ; pop off the old A2 
UNLK A6 
MOVE.L (А72%,А0 ; Save the return 

; address 
ADD.L 812 AT ; move the stack 

; pointer clear all 

; the data off the 

; Stack 
CLR.W (АТ) ; replace the return 


; value on the stack 
; with ours 


** NOTE: we are pushing a value of zero 
onto the stack, meaning that nothing went 
wrong. This is bogus and in the real 
version we need to fix this! 


Wwe We We Ve 


MOVE.L A0,-(A7); push the return 
; address back onto 


~ 


; the stack 

RTS ; return to reality 
; Cour calling 
; program) 

ENDF 

END 


The 68000 Instructions: 

First of all the basics. Anything after a semicolon (4; ”) is 
a comment and not a command. Our Assembler will ignore all 
comments, just as if they had never been typed in. Each line of 
code has three basic parts!!. If you look at the code you can see 
that it seems to be divided into three columns. The first column 
begins with the first character of each new line and is called a 
label. Labels are used so we can refer to that line of code from 
within our program. Anything in the second column is an 
instruction for the 68000 (or the 68881). Anything in the third 
column tells the chip how (and where) to execute that instruction. 

A couple of the instructions that appear at the beginning of 
the program are actually instructions for the Assembler’? and not 
the chip. The instruction “EQU” asin “RetumAdd EQU 4" tells 
the Assembler to substitute the number “4” every time it sees the 
label *ReturnAdd" in our code. We could have written the 
number 4 in ourselves, but using the label “ReturnAdd” makes 
our code a lot more understandable. FUNC tells the Assembler 
that this is the name of a function. The word EXPORT tells it to 
let the rest of the world know that a function exists by the name 
*ScaleMult" and where that function can be found. MC68881 
states that we will be using some of the 68881 instructions 
(otherwise our Assembler would say we must be making a 
mistake when we try to use them). MACHINE MC68020 lets 
the Assembler use instructions that are available only on the 
68020 chip on a Mac II. The MPW Assembler will replace some 
of our instructions with it’s own if it sees a faster way of doing the 
same thing. This is called optimizing the code. If you are not 
running with a 68020 delete this line. OPWORD is similar to 
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EQU except that it lets us define a new instruction by its numeric 
equivalent, whereas EQU lets us define a constant used by the 
instruction. ENDF and END signal that we are finished writing 
our function and code, respectively. 

The 68000 chip has several registers for holding numbers. 
These can be thought of as Mail Box slots if you will. A mail box 
can either hold a parcel (your data) or a slip telling you where 
your parcel is (an address). Ош registers take 32 bit numbers and 
hold them on the chip. Eight slots (or "registers") hold simple 
data. Another eightregisters hold 32 bit addresses (see Figure 1). 
Address are simply numbers that tell the Mac which byte in the 
memory holds your data. 0 is the first byte in RAM, 1 is the 
second, etc. Remember that both Data and the Address registers 
hold simple 32 bit numbers. These registers are referred to as DO, 
рі, ..., D7 for the data and AO, A1, ..., A7 forthe Addresses. То 
manipulate numbers on the computer we simply move a number 
from RAM, into one of these registers, do what we wantto it, then 
putit back. The fact that the 68000 CPU has so many registers 
on the chip means that we don't have to swap back and forth 
between RAM and the chip nearly as often as you had to on older 
chips. Our basic command for moving data around is "MOVE" 
(doesn't that make sense?). 


68000 CPU 
А0 


68881 FPP 


FPO 
FP1 
FP2 
FP3 


FP4 
FPS 
FP6 
FP? 


other stus — — — —] | |, 


Figure 1. The Microprocessors 


To get a number that is stored in the 128th byte of RAM, and 
move it to register D1 on our chip would simply write “MOVE 
128,D1” (see Figure 2). To actually place the number 68 into 
register D1 we would say "MOVE #68,D1” (see Figure 3). The 
symbol “ #” means to take the number and use it literally, versus 
using the number as the address of our data, as we showed in 
Figure 2. 

Putting the name of aregister in parentheses means to use the 
address stored within that register to find our data. This is shown 
in Figure 4. The same instruction without the parentheses means 
to use the contents of the register directly, as shown in Figure 5. 


Basic 68881 Commands 

Notice that many of the instructions have suffixes attached 
to them, such as MOVE.W or MOVE.L (and MOVE.B). These 
simply tell the 68000 what size number we are moving, “.В” for 
a Byte (8 bits long), “№” fora Word (16 bits long and the default 
if you forget to specify a suffix), or finally “.L” for a Long word 
(or 32 bits). Some of the Floating Point instructions specify a 
* X" which tells the 68881 to move three long words (or the 96 
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Figure 2. MOVE 128, D1 
(get the data from memory 
location 128) 


66000 
CPU 
D] 


Figure 3. MOVE #68, D1 
(put 68 in register D1) 
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Figure 4. MOVE (A1), D! 
(register A1 contains the 
address of our data) 


68000 
CPU 


Figure 5. Move A1, D1 
(register A1 contains the data) 


bits it takes to specify an extended 
number). The “.X” extension is only 32 16 
understood by the 68881, so if you 
added it to a 68000 instruction, the 
CPU would not know what you 
where talking about. When we move 
different size numbers onto the chip 
they arealways placed so that bit zero 
is aligned all the way to the right. 
Thus the three numbers would be 
stored as in Figure 9. 

The instruction FMOVE works 
the same way as MOVE, but allows 
you to move numbers to and from the 
68881 coprocessor chip. By using 


— 
БЕНЕН ШАҒА»; 22: | | 


Figure 6. How Numbers Are 
Stored in the 68000 Registers 


the suffix “.X” (asin FMOVE.X) we T T T 
can tell the coprocessor that you are 
manipulating a 96 bit extended 3824019342310000 


number, although “І”, “уу” “В” 
will also work if you are referring to 
these quantities. The 68881 FPP has 
8 registers of it’s own (FPO to FP7), 
each with enough room to store an 
extended number. 


Figure 7. How numbers are 
stored in RAM 


Bits and Bytes 

I am not going to go over a lengthy explanation of bits, bytes, or how to 
convert between decimal numbers and hexadecimal numbers (since these are just 
different ways of writing the same number). There are many good books on these 
kinds of basics, and they are referred to in the appendix |131, 

The 68000 stores numbers in memory in the same way that you would read 
them from a piece of paper. It starts at a low memory address and writes the 
number, starting with the most significant digit and going to the least significant 
digit. If another number is to be written, it will repeat the sequence. Thus if I was 
going to store the number $38240193 at memory location 128, and then store the 
number $42310000 in the next highest position (which would start at memory 
location 132) the memory would appear as in Figure 7. 

The stack is a key concept to writing assembly language. The best example 
of a stack are those old plate stackers that we all remember from the school 
cafeteria. If you imagine that each plate is a number, you simply place the next 
"plate" on the stack, piling them up as you go. If you need a plate, you simply pop 
itoffthe top. The 68000 uses the same concept to store numbers. To define a stack 
you first pick where in memory you want to start. This starting address is usually 
placed in register A6 (this is simply a convention and we could just as easily 
stashed it in A4 or any other register). We then place a number on the stack (we 
call this pushing the number onto the stack) by simply writing the number into 
memory, using the memory location pointed to by register A6. The next thing we 
want to keep track of is the end of our stack. We can do this using another one 
of our registers, A7. If we just added 2 bytes to the stack by pushing our number 
, then we need to adjust register A7 to point to the next free byte of memory, or 
in other words, the end of the stack. 

What if we want to take the top number off of the stack? A7 points to the top, 
so we get our number, move it somewhere else, then change A7 to point to the new 
top of the stack. Using this system we can push numbers onto the top of the stack, 
and pop them off at will. This type of memory arrangement is called a Last In/ 
First Out system, since the last number we pushed onto the stack is the First 
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number we have available to pop off again. 

Most computer systems use the stack as a method of storing 
numbers. The only little twist to the way the Macintosh handles 
a stack is that instead of starting at a low memory address and 
working higher, the Macintosh starts at a High memory address 
and works downward, toward lower memory. This twist doesn’t 
change the way we work with the stack. If we decide that we want 
to start our stack at memory address 128, we store 128 in register 
A6 and then set A7 to point to the end of the stack, which in this 
case is also 128. We now want to add a 4 bytes number onto the 
stack ,such as $32411000. We simply subtract 4 from the address 
in A7 (or 128 - 4 = 124), and Move our 4 byte number to RAM, 
starting at address 124. This is accomplished with the command 
“MOVE.L #$32411000,-(A7)”. If we look at the RAM, starting 
at address 124 we will now see the number $32411000. 

Take a close look at the instruction we just issued. By 
appending .L to the MOVE command we have told the assembler 
that we are moving a long word, which is by definition 4 bytes 
long (or 32 bits). The #$32411000 portion used tells the 68000 
to use the number $32411000 literally. Finally the command “- 
(A7)” does something special. It tells the 68000 to subtract the 
length of our longword, 4, from the address stored in A7, and 
place the resulting address back in A7. It also does this before it 
executes the MOVE instruction, so our number gets moved to 
address 124 instead of 128. This leaves 124 in A7 when we are 
finished so our stack pointer now points to the end of the stack 
again. We call this kind of addressing “Predecrement Indirect". 
Don't worry about what this mode of addressing is called, just 
take note of what it does. The fact that the 68000 can do these 
kinds of instructions in one step makes life very simple for us. 
The 68000 can also do the converse operation. Lets say we want 
toremove our number and store itin RAM starting at address 200. 
We will then issue the command “MOVE.L (A7)+, 200". Again 
the suffix “.L” tells us that we are dealing with a 4 byte longword. 
Note that if we used *.W" instead the 68000 would do the same 
calculation, but know that we were talking about moving a (2 
byte) word instead. Our original command, MOVE.L, will get 
the 4 byte number, starting at the memory location pointed to by 
register A7,and movethat number to memory address 200. After 
itis done, it will add 4 to the address stored in register А7 so that 
A7 now contains 124-4 or 128, which is the top of the stack 
again. This type of addressing is called Postincrement Indirect. 
We have just successfully pushed a 4 byte number onto the stack, 
and then popped it off again, all the time keeping register A7 
pointing to the end of the stack. 

We can use this algorithm to push many numbers onto the 
stack, one after another. This is exactly what a Pascal program 
does when it calls your assembly language subroutine. It pushes 
all the variables it is going to hand you onto the stack, and then 
jumps to your routine. Since we know the kinds of numbers that 
the main program will pass to us, we can pop them off, do our 
calculation, push our result back onto the stack, then jump back 
to the main program. We will talk more about actually doing this 
a little later. 


© The Best of MacTutor, Vol. 5 


(A6) The Stack 


Grows 
Downward in 


Memory, 
Starting at the 
Address in 
Register -Ab 
and ending 
iust before the 
address 
stored in 


і Register A7 


Figure 8. The Macintosh Stack 


More Instructions 

Let's look at a few more Assembly language instruc- 
tions. The instruction CLR (which stands for Clear) will put all 
zeros at an address. Thus “CLW.W 128” will put 2 bytes worth 
of zeros starting at address 128. CLW.L (А1) will store 4 bytes 
worth of zeros at the address stored in register Al. CLW.B D1 
will fill the 1st byte of register D1 with zeros. 

The instruction ADD will do what it’s name would suggest. 
“ADD.L D1,D2” will add the two long words stored in registers 
D1 and D2 and store the result in D2. *ADD.W (A1)+,D1” will 
getanumber from memory, stored at the address contained in A1. 
It will then add that number to the number stored in D1. The final 
result is stored in D1. The fact that we wrote “(А 1)+” means that 
after it completes all of this addition, it will increase the address 
stored in A1 by 2 (since we specified .W). This is very useful if 
we are adding a bunch of numbers to D1 and they are stored in 
memory one after another starting at the address in Al. After we 
execute our “ADD (A1)+,D1” command, A1 now automatically 
points to the next number in memory. This command, when 
placed in a simple loop, is a powerful way to add many numbers. 

Another use for this type of addressing to move a range of 
bytes from one part of RAM to another. If we store the beginning 
address of our data in A1, and the address of the place we want 
to move it to in A2, by repeatedly calling 
*MOVE.L (A1)+, (A2)+” we move our data from (A1) to (A2) 
in RAM, afterwards both the addresses stored in A1 and A2 are 
automatically incremented by 4, so we are ready to move the next 
long word. Nifty, isn't it? 

The commands LSR and LSL stand for Logical Shift Right 
and Logical Shift Left. What they do is move each bit in memory 
to the right or left a certain number of places. The bits that fall 
off the end disappear!^, and the places that we leave empty are 
replaced by zeros. An example of a Logical Shift Left is shown 
in Figure 9. "LSL.L #5,D1” will shift the binary number stored 
in register D1 to the left 5 places by pushing zeros onto the right. 
A LSR instruction works in the converse fashion 

LSR and LSL will become important later on when we want 
to quickly manipulate our numbers. The next instruction that we 
use a bit is LEA which stands for Load Effective Address. An 
example might be "LEA Scalar(A6),A2". This instruction cal- 
culates the address using the code 16(A6) and stores that address 
in register A2 (remember that we had defined the label Scalar to 


(А7) 
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be the same as the number 16). Note that it doesn’t go to the 
address, just calculates what it should be. Unfortunately you 
probably don’t know what 16(A6) would be, but it is not hard to 
figure out. We take the address stored in register A6 (lets say it’s 
our old friend 128 again) and add 16 to it. Take the result (128 
+ 16 = 144) and put itin A2. We can now use the address in A2 
for other instructions. This type of instruction is good if we know 
we wanta number stored 16 bytes away from some base address, 
and that base address will be given to us later. When we get that 
base address, we can store it in A6 and use our LEA instruction 
to find the address of our data. Many times we will know the form 
a bunch of data, i.e. an integer is stored first, then a real number, 
then a pointer to an array (i.e. the address of some other data), but 
we won't know exactly where this data is going to be in RAM. 
LEA lets us get the beginning of our data and calculate where 


16 8 0 


D1 Before 


1:1:1:1:1:1-1-1]1-1-1:0-0-0-0:0] D1 After 


1-1-1-1 - 


Figure 9. LSR #5, D1 


everything else should be. 

The final instruction that we need to look closely at are the 
LINK and UNLK instructions (i.e. “LINK A6,#-12” & “UNLK 
A6"). If you remember when we were talking about stacks, we 
said we would remember the beginning address of the stack by 
putting it in register A6. The technique of beginning your stack 
at Аб is called stack frames. The way it works is as follows: Тһе 
main Pascal program has it's own stack. It pushes all of the data 
it needs to give your subroutine on it's stack. Finally it pushes a 
return address onto the stack (so you know which instruction to 
return to when you're done executing your code), and then jumps 
to your assembly code. You dutifully save the return address by 
popping it off the stack and moving it someplace safe. You then 
pop all of the data off the stack and are ready to go. 

At this point you most likely want to create your own stack, 
and the best place is right at the end of the main program's stack. 
The first thing you do is save the old value of A6 that marks the 
beginning of Pascal's programs stack. A great way to store this 
value is to push itright onto the stack. Take the new value of A7 
(the address that we are going to use as the base of our new stack) 
and store that in A6. We are now ready to go. A6 and A7 both 
point to the beginning of our stack. We then increment the stack 
pointer (A7) to make room for any storage space that you might 
want to use. As we push and pop values to and from our stack we 
will adjust A7 appropriately with the predecrementing and 


44 


postincrementing commands that we discussed. These steps are 
illustrated in Figure 10. Allofthesteps necessary to create a stack 
frame are contained in the LINK instruction. The instruction 
"LINK Аб, 4-12" will first push Аб onto the stack after decreas- 
ing A7 by 4 (since an address is along word of 4 bytes). The new 
new value of A7 is copied into A6, since that will be the base of 
our new stack. Finally the stack pointer A7 is decremented by 12 
bytes to make room for new data that we might want to store 
there. In this case we decremented the stack by 12 since, if you 
remember, our stack grows downward in memory. Decreasing 
A7 by 12 leaves room for 12 new bytes of storage space (which 
would be just enough room for us to stash a 96 bit extended 


high memory 
did (Аб) 
new (A6) 


room kr 
new іс 


AJ (slack 
painter) 


s 


Figure 10. The Stack After LINK 


number in the 68881 format!). 

The nice thing about having A6 point to the beginning of our 
stack is that when we are ready to jump back to the main program 
we can take A6 and copy it into A7. That maneuver has just made 
our stack pointer point to the bottom of our stack frame. We then 
pop the old value of A6 off the stack and put it back into register 
A6, then add 4 to the contents of A7, just like our old friend the 
"MOVE (A7)+,A6” instruction. We now have returned the stack 
to it's state just before we created our stack frame. The 68000 
does all of this with another single instruction UNLK. In our 
case "UNLK A6" will do all of the above steps. 

The second nicety of having A6 point to the bottom of our 
stack frame is that we can easily store our own variables on the 
stack. Although we do notknow in advance where A6 will point, 
we do know the relative position of our data on the stack. Let's 
say one variable will be located 4 bytes before A6, another will 
be 6 bytes before A6, etc. By using addresses of the form -4(A6) 
and -6(A6) we can access these variables whenever we need to. 

Another advantage of addressing all of our data relative to 
the stack frame in (A6), is that we don't necessarily have to waste 
time moving the variables that we received from our Pascal, off 
of the stack. Since we know what the stack looks like after we 
execute our "LINK A6,#-12” instruction (see Figure 10) we 
know that the pointer to inMatis located 8 bytes prior to (Аб), and 
that outMat will be 12 bytes before (A6). We then use the same 
form of addressing (e.g. “MOVE.L 12(A6),A@”) to move out- 
Mat to AØ so we can work with it. 

In order to quickly manipulate every element in our matrix, 
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We will create a loop that performs our calculation, then repeats 
itself with the next element in the matrix, until we get to the end. 
To create a loop and test for a specific condition (so we know 
when to stop looping) we will use the instruction DBLT (decre- 
ment and branch if less than zero). This is one member of a class 
of instructions written in shorthand as DBcc, where cc is a test. 
The easiest way to think of this instruction is don't branch if the 
condition is true. The instruction works by first testing if the test 
condition is true, i.e. did we just execute an instruction that 
resulted in an answer that was less than zero (or in other words a 
negative number). If the prior instruction created a negative 
number then don't branch (which would then leave our loop, just 
as branching would bring us back to the beginning of our loop), 
but instead execute the next instruction. Now if the last instruc- 
tion created a positive number (and thus the test failed) then we 
decrease the register D1 by one and see if D1 is now less than 
zero. If itis, then we don't branch but instead continue on to the 
next instruction. If neither of these condition are true then round 
we go again, branching to the beginning of our loop. This 
instruction has several advantages. First it looks for a specific 
condition that will end the loop. Failing this, it counts down a 
register until it is less than zero and then exits the loop. 

The last instruction in our program is RTS (Return from 
Subroutine). This instruction assumes that we have pushed the 
return address back onto the top of the stack and will jump to that 
address. If we had stored our return address іп AØ we could have 
accomplished the same feat by using the command “JMP (А0)” 
(jump to the address stored in register AQ). 


SANE vs. the 68881 

Although SANE and the 68881 both use the same basic 
format for an extended number, there is one fundamental differ- 
ence. In SANE the extended number is 80 bits (10 bytes) long. 
On the other hand, the 68881 places two bytes of zeros just before 
the last word in the number (this is illustrated in Figure 11). The 
68881 does this because it is more efficient for it to move three 
long words than to manipulate 2 1/2 long words. We can easily 
convert back and forth between these formats by grabbing the last 
word of a SANE extended number and shifting it over 16 spaces 
to the left (using the LSL instruction). When we want to return 
the number to SANE we simple shift the top long word of our 
68881 extended number back to the right 16 spaces (using 


80 TEMO 0 
| p | | | _ 
96 — 80 64 0 


68881 -Exttendedformad 
Figure 11. SANE vs. 68881 extended numbers 


LSR)*. 
The interface for a Pascal calling routine 
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A Pascal program calls a procedure ina very orderly fashion. 
In our example the procedure that we will write in assembly 
language is declared to Pascal as: 


FUNCTION ScaleMult (scalar : 
matrix) : integer; 
external; 


extended;VAR inMat, outMat : 


Pascal will prepare to call our subroutine by first pushing 
enough space onto the stack for our result. If our subroutine was 
declared as a procedure, Pascal would not expect a return value 
and would skip this step. Following this, Pascal pushes it's data 
onto the stack as read from left to right. In our case Pascal would 
next push a pointer to the variable "scalar". Pascal pushes a 
pointer! to the data if it is declared as a VAR parameter (meaning 
that the subroutine can change the actual variable), or if the data 
is larger than four bytes in size". A pointer to inMat is then 
pushed onto the stack followed, by a pointer to outMat. Finally 
the return address is pushed onto the stack and the program then 
jumps to our subroutine. Pascal cannot do any type checking 
when it jumps to an assembly language routine. It simply 
assumes you know what kind of data you are expecting, and that 
you will place the correct result on the stack (if your routine is a 
function and not a procedure) when you return to the main 
program. 

When the Pascal calling routine tries to make space for the 
return variable (the very first thing we said that Pascal would 
push onto our stack if itis calling a function) it follows the Pascal 
rule of pushing the actual variable if it is 4 bytes or less, or, as is 
the case of our extended variables which is larger than 4 bytes, it 
pushes a pointer to the variable. We would then use that address 
to store the result of our functions. When we return to Pascal we 
would leave the address of our return variable on the stack so the 
calling Pascal program can remember where to get its result. 

In our assembly language program we will remove all the 
information from the stack, complete our routine, then push an 
integer (2 bytes) onto the stack as a result. Our final maneuver 
will be to jump back to the return address that was given to us 
initially. Figure 12 shows us the stack as it would appear when 
we initially enter our subroutine. 


high 
return 
value 


pointer to low word 
high word 
pointer to low word 
high тога 
pointer to low word 
high word 
return low word 
high word 
low memory 


Figure 12. The Stack as passed from Pascal 


One point I would like to clarify is this business of Pascal 
pushing a pointer onto the stack if that variable is more than four 
bytes long, or if itis declared as a VAR in the interface statement. 
Figure 13 shows the size of some common variables used in 
Pascal. 
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Variable What is passed on the stack 


integer 2 bytes 

longInt 4 bytes 

real 4 bytes 

extended 4 byte pointer to the 10 bytes SANE 
extended number 

pointer 4 bytes 

string 4 bytes pointer to your string if it is 
over 4 bytes in size) A 
string takes up n+1 
bytes where n is the 
number of characters. 
The very first byte tells 
you how many 
characters are in the 
string. 

boolean 2 bytes (put your result in the 
least significant byte of 
the word when you 
return to Pascal) 

char 2 bytes 


anything 4 byte pointer to the variable in RAM 
declared as “var” 


Figure 13. Size of Pascal Variables Pushed onto 
the stack 


Remember, if we wrote a procedure instead of a function we 
would leave the stack empty when we returned to the main 
program. An illuminating example would be if we had declared 
our function to return an extended number. Since we don't want 
to push the entire 10 bytes of data onto the stack we simply store 
our data at the address supplied by the calling routine. I always 
considered it courteous of Pascal to take care of the memory for 
any variables our function needs to return. 

In our program, we are returning an integer which is two 
bytes in size, so we can just push the actual value of the integer 
onto the stack, and not worry about pointers at all. Remember 
that Pascal has already made enough room on the stack to hold 
our integer. 

Pascal lets us freely use registers AO, A1, DO, D1, and D2. 
We can of course use any of the registers on the 68000 chip, just 
so long as we save the values that are stored there and put them 
back, before we return to the Pascal environment. 


The Code 

Now that we understand all the the basic instructions, lets go 
through our assembly language code. Our program receives 
three pointers (or addresses) from Pascal. The data is stored at 
these addresses in SANE extended number format. We take each 
of these numbers, and shift over thc top word so it is in the correct 
format for the 68881 chip. Next, we move one element of our 
matrix (from inMat) onto the 68881, along with the scalar, 
multiply them, then save the result in the output matrix (outMat). 
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We repeat this for all of the numbers in our matrix before 
returning to the main program. The LINK instruction is used to 
illustrate how we can make room on the stack for our own 
variables, easily accessing them relative to the base of the stack. 
Our funny data structure for an element may make a little more 
sense now, in light of the above differences between the SANE 
and 68881 representation of an extended number. Each element 
of our vector is a record of the form 


element = PACKED RECORD 


empty : integer; 
n : extended 
END; 


the empty integer that I have thrown before each SANE 
extended number takes up one word of space (16 bits). This gives 
us enough room to change all of our 80 bit SANE extended 
numbers into the larger 96 bit 68881 format. Because we have 
this extraroom wecan store our numbers right back in their array. 
This may not be important for our simple little program, but if we 
were doing alotof math with these numbers, converting back and 
forth for each mathematical operation would take a lot of time. 
This way we can convert each element to the 68881 extended 
format when we start our program and convert them all back to 
the SANE format when we are finished. 


A vector is simply defined as an array of many elements. 


vector = ARRAY[®..19] OF element; 
matrix = RECORD 
rows : integer; 
columns : integer; 
vecPtr : ^vector 
END; 


A matrix is a data structure that specifies the number of rows 
and columns it will contain, followed by a vector that is rows Y 
columns in size. Again, all of this is not strictly needed for our 
code, but it does illustrate how we can write a general algorithm 
that would take an matrix of an arbitrary size, do whatever math 
Is needed, and then store the results in a new matrix. 


How to Compile and Put the Program Together 

I have always hated articles that give you great code!$, but 
then leave you in the lurch as to exactly how they put it all 
together. I'm going to give instructions for using the MPW 
compiler, since it already supports the 68881 and 68020 chips. 

First of all open the MPW shell and type Command-N to 
get a fresh document. Type in all of the Assembly code, as it is 
written (of course you can leave out the comments if you want). 
Save this document as “ScalarMult.a”. Click on the Worksheet? 
and type the Magical incantation “Asm ScalarMult.a" followed 
by the enter key (or Command- RETURN if you don't have an 
enter key on your keyboard). [Please note that the return key and 
enter key are treated differently in the MPW environment.] If 
you didn't make any mistakes then MPW will have just created 
a file named “ScalarMult.a.o”. If everything worked out alright 
then quit MPW. 
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Version 1.11 of LightSpeed Pascal includes a little utility 
called the “.О converter”; Double click on this icon, then select 
our assembly code file “ScalarMult.a.o” from the dialog box. 
After you quit “.O converter”, You will see that we have just 
created a LightSpeed library file. 

Our final chore will be to launch LightSpeed Pascal and open 
anew project. First geta fresh window up, and type in the Pascal 
main program. Next go to the “Project” Menu and select “Add 
Files...". Add the main program that we just typed in, along with 
the library file we created from our assembly code. That's all 
there is to it!. You can either run the program by typing 
Command- G (for Go) from within Lightspeed, or elect to build 
a stand alone program”. 

Remember that our procedure will jump into Macsbug as 
the first instruction, so that we can follow the program. If you 
don't have Macsbug in your system folder , remove the 
instruction “ Debugger" or the computer will bomb with an 
ID=1 error 


Summary 

In this article, I hope I have introduced enough basic infor- 
mation to let you write an assembly language subroutine. We 
looked at the basic 68000 instructions, and a few instructions 
from the 68881 numeric coprocessor ships. As we saw 68881 
instructions are easily executed, as if they were part of a souped 
up 68000 CPU. 

We saw how Pascal calls functions and procedures and we 
created a short assembly language subroutine that could stored 
it’s own local variables and manipulated them. Finally we looked 
at how to compile and interface the assembly language using 
Light Speed Pascal and the MPW assembler. I hope that this 
introduction lets you see that assembly language is not as intimi- 
dating as it looks, and that by selectively rewriting certain Pascal 
procedures we can realize great increase in the speed of many of 
our programs, especially those that are calculation intensive. 


Footnotes 


1. Apples “Standard Apple Numeric Environment" which 
handles complex math very well, if not a little slowly 

2. Note that in many cases we are presenting a simplified 
picture of what our Assembly language instructions do. If you 
are an experienced Assembly language programmer, you may 
note some deviations from fact (i.e. white lies). This is to shield 
the inexperienced user with unnecessary, complicating details, 
and will be noted. Come to think of it, if your such a hot shot 
programmer, why do you need to read this? See any of the books 
in the reference section for a more complete picture of Assembly 
Language programing. 

3. FPP 

4. Central Processing Unit. 

5. I know... when you ask the salesman, they've never heard 
of it. 

6. Macintosh Programmers Workshop 

7. And the only native Mac language system supported by 
Apple for a long time 
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8. Yes, I know the "definition" of AsSUMe. 

9. If you didn't know it, you do now. 

10. A hexadecimal number is a number, similar to our 
ordinary base 10 counting numbers. Instead of counting from 
zero to nine (then indicating ten by putting a one in the next 
significant place, as in 10), in hexadecimal we count from zero 
to fifteen (representing the numbers ten through fifteen with the 
symbols A through F). We would then represent the next 
number, 16, by putting a one in the next significant place as in 
$10. I will use the “$” sign before any hexadecimal number to 
you don't confuse $10 with the decimal number ten. Hexadeci- 
mal notation is a convenient way to write numbers when we deal 
with computers. See any of the books in the reference section for 
a good review of the subject. 

11. Not counting the comments 

12. The program that translates our written words into the 
actual numbers that the 68000 and 68881 understands 

13. At least for us humans. The computer prefers numbers 
and will substitute numbers for all of our words, including the 
instructions. Oh well... to each his own. 

14. Not exactly, each bit first goes to a place called a Carry 
Bit, before it drops off into never never land, but that's not really 
important. 

15. Aneven easier way to accomplish the same thing would 
beto MOVE the last word over, for example using the instruction 
“MOVE 8(AQ), 10(А0)”, provided AØ pointed to the begin- 
ning of our extended number. You should always follow the 
above instruction with CLR.W 8( АО) to ensure that the bit 64 
through 80 are zero, just to ensure compatibility with future 
products. 

16. A pointer is simply the address of where our data starts 
in RAM 

17. Note that the pointer given to us actually points to a copy 
of the variable, known as a “dummy variable". This will prevent 
us from accidentally changing the value of the variable in the 
main program. 

18. Don't worry, I' m not assuming that you have gotten any 
great code from this article 

19. Its the document that doesn't have a go-away box 

20. Of course you could have complied and linked you 
program totally from within MPW and MPW Pascal, but if you 
know how to do all of that, you probably didn't need my help to 
begin with. 
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C Workshop 


Bezier Curve Ahead! 


David W. Smith (no known relation to the Editor) is a Sr. 
Software Engineer at ACM Research, Inc., in Los Gatos. 

There comes atime in the development of some applications 
when arcs and wedges just don’t cut the mustard. You want to 
draw apretty curve from point A to point B, and QuickDraw isn’t 
giving you any help. It seems like a good time to reach for a 
computer graphics text, blow the dust off of your college math, 
and try to decipher their explanation of splines. Stop. All is not 
lost. The Bezier curve may be just what you need. 

Bezier Curves 

Bezier curves (pronounced “bez-yeah”, after their inventor, 
a French mathematician) are well suited to graphics applications 
on the Macintosh for a number of reasons. First, they're simple 
to describe. À curve is a function of four points. Second, the 
curve is efficient to calculate. From a precomputed table, the 
segments of the curve can be produced using only fixed-point 
multiplication. No trig, no messy quadratics, and no inSANEity. 
Third, and, to some, the most important, the Bezier curve is 
directly supported by the PostScript curve and curveto opera- 
tors, and is one of the components of PostScript's outlined fonts. 
The Bezier curve is also one of the principle drawing elements of 
Adobe Illustrator™ . (Recently, they've shown up in a number of 
other places.) 

Bezier curves have some interesting properties. Unlike 
some other classes of curves, they can fold over on themselves. 
They can also be joined together to form smooth (continuous) 
shapes. Figure 1 shows a few Bezier curves, including two that 
are joined to form a smooth shape. 

The Gruesome Details 

The description of Bezier curves below is going to get a bit 
technical. If you’re not comfortable with the math, you can trust 
that the algorithm works, and skip ahead to the implementation. 
However, if you’re curious about how the curves work and how 
to optimize their implementation, or just don’t trust using code 
that you don’t understand, read on. 

The Bezier curve is a parametric function of four points; two 
endpoints and two “control” points. The curve connects the 
endpoints, but doesn’t necessarily touch the control points. The 
general form Bezier equation, which describes each point on the 
curve as a function of time, is: 

P(t) = w, (OP, + м.ОР, +w, (OP, + w,(OP, 


where P, and P, are the endpoints, P, and P, are the control 
points, and the w "5 are weighting functions, which blend the four 
points to produce the curve. (The weights are applied to the h and 
v components of each point independently.) The single parame- 
ter t represents time, and varies from O to 1. The full form of the 
Bezier curve is: 
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Figure 1. Some Beizer Curves and Shapes 
P(t) = (t-1)°P, + 3t (t-1)P, *3t(1-0?P, + P, 


We know that the curve touches each endpoint, so it isn't too 
surprising that at t=0 the first weighting function is 1 and all 
others are O (i.e., the initial point on the curve is the first 
endpoint). Likewise, at t=1, the fourth weighting function is 1 
and the rest are 0. However, it's what happens between 0 and 1 
that's really interesting. A quick side-trip into calculus to take 
some first derivatives tells us that the second weighting function 
is maximized (has its greatest impact on the curve) at t=1/3, and 
the third weight is maximized at t=2/3. But the clever part—the 
bit that the graphics books don't bother to mention—run the 
curve backwards by solving the equation for 1-t, and you find that 
w, (t)=w,(1-t) and w,(t)=w,(1-t). As we'll see below, this sym- 
metry halves the effort needed to compute values for the weights. 


Implementing Bezier Curves 

One strategy for implementing Bezier curves is to divide the 
curve into a fixed number of segments and then to pre-compute 
the values of the weighting functions for each of the segments. 
The greater the number of segments, the smoother the curve. 
(I've found that 16 works well for display purposes, but 32 is 
better for hardcopy.) Computing any given curve becomes a 
simple matter of using the four points and the precomputed 
weights to produce the end-points of the curve segments. Fixed- 
point math yields reasonable accuracy, and is a hands down 
winner over SANE on the older (pre-Mac IT) Macs, so we'll use 
it. 

We can optimize the process a bit. The curve touches each 
endpoint, so we can assume weights of O or 1 and needn't 
compute weights for these points. Another optimization saves 
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both time and space. By taking advantage of the symmetric 
nature of the Bezier equation, we can compute arrays of values 
for the first two of the weighting functions, and obtain values for 
the other two weights by indexing backwards into the arrays. 

Drawing the curve, given the endpoints of the segments, is 
the duty of QuickDraw (or of PostScript, if you're really hack- 
ing). 

The listing below shows a reasonably efficient implementa- 
tion of Bezier curves in Lightspeed CTM. A few reminders about 
fixed-point math: an integer times a fixed-point number yields a 
fixed-point number, and a fixed by fixed multiplication uses a 
trap. The storage requirement for the algorithm, assuming 16 
segments, (32 fixed-point values), is around 32*4*4, or 512 
bytes. The algorithm computes all of the segments before 
drawing them so that the drawing can be done at full speed. 
(Having all of the segments around at one time can be useful for 
other reasons.) 


More Fun With Curves 

Given an implementation for Bezier curves, there are some 
neat things that fall out for almost free. Drawing a set of joined 
curves within an OpenPoly/ClosePoly or an OpenRgn/ 
CloseRgn envelope yields an object that can be filled with a 
pattern. (Shades of popular illustration packages?) For that 
matter, lines, arcs, wedges, and Bezier curves can be joined to 
produce complicated shapes, such as outlined fonts. Given the 
direct mapping to PostScript’s curve and curveto operators, 
Bezier curves are a natural for taking better advantage of the 
LaserWriter. 

As mentioned above, Bezier curves can be joined smoothly 
to produce more complicated shapes (see figure 1). The catch is 
that the point at which two curves are joined, and the adjacent 
control points, must be colinear (i.e., the three points mustlay on 
aline). If you take a close look at Adobe Illustrator's drawing 
tool, you'll see what this means. 

One nonobvious use of Bezier curves is in animation. The 
endpoints of the segments can be used as anchor-points for 
redrawing an object, giving it the effect of moving smoothly 
along the curve. One backgammon program that I’ve seen moves 
the tiles along invisible Bezier curves, and the effect is very 
impressive. For animation, you would probably want to vary the 
number of segments. Fortunately, the algorithm below is easily 
rewritten to produce the nth segment of an m segment curve 
given the the end and control points. 

Further Optimizations 

If you're really tight on space or pressed for speed, there are 
afew things that you can do to tighten up the algorithm. A bit of 
code space (and a negligible amount of time) can be preserved by 
eliminating the setup code in favor of statically initializing the 
weight arrays with precomputed constant values. Drawing can 
be optimized by using GetTrapAddress to find the address in 
ROM of lineto, and then by calling it directly from inline 
assembly language, bypassing the trap mechanism. I've found 
that neither optimization is necessary for reasonable perform- 
ance. 
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/* 

** Bezier - Support for Bezier curves 

** Herein reside support routines for drawing Bezier curves. 
** Copyright (C) 1987, 1988 David W. Smith 

** Submitted to MacTutor for their source-disk. 

*/ 


#include ¿“Maclupes.h> 
x 


The greater the number of curve segments, the smoother the 
curve, and the longer it takes to generate and draw. The 


number below was pulled out of a hat, and seems to work o.k. 
x 


"define SEGMENTS 16 


static Fixed weight 1[SEGMENTS + 1); 
static Fixed weight2ISEGMENTS + 11; 


define и1(8) weighti[s] 

"define w2(s)weight2[s] 

Sdefine w3(s) weight2(SEGMENTS - s] 
def ine w4Cs) weight (SEGMENTS - s] 


/* 
% SetupBezier - one-time setup code. 
* Compute the weights for the Bezier function. 


* For the those concerned with space, the tables can be 
precomputed. Setup is done here for purposes of illustration. 
*/ 


void 

an 
Fixed t, zero, one; 
int s; 


zero = FixRatio(0, 1); 

one = FixRatioC1, 1); 

weight1[0] = one; 

weight2[0] = zero; 

for (s = 1; з ‹ SEGMENTS ; ++ ) ( 
t = FixRatio(s, SEGMENTS); 
weightl[s] = FixMul(one - t, FixMul(one - t, one - t)); 
weight2[s] = 3 * FixMulCt, FixMulCt - one, t - one)); 


weight 1[SEGMENTS] = zero; 
weight2[SEGMENTS] = zero; 


/* 
* computeSegments - compute segments for the Bezier curve 
* Compute the segments along the curve. 
* The curve touches the endpoints, so don’t bother to 
compute them. 
*/ 
static void 
computeSegments(pl, p2, p3, p4, segment) 


Point pl, p2, p3, på; 
Point segment[]; 
int S; 


segment [0] = pl; 
for (s= 1; s < SEGMENTS ; ++s ) ( 
segment[s].v = FixRound(w1Cs) * pl.v + w2(s) * p2.v + 
w3(s) * p3.v + w4(s) * p4.v); 
segment[s].h = FixRound(w1Cs) * pi.h + w2(s) * p2.h + 
w3(s) * p3.h + w4Cs) * p4.h); 


) 
segment[SEGMENTS] = p4; 
/* 


* BezierCurve - Draw a Bezier Curve 
* Draw a curve with the given endpoints (pl, p4), and the 
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given 
* control points (p2, p3). 
x Note that we make no assumptions about pen or pen mode. 
*/ 

void 

BezierCurve(p1, p2, p3, p4) 


Point pl, p2, p3, p4; 
int s; 
Point segment [SEGMENTS + 1]; 


computeSegments(p1, p2, p3, p4, segment); 
MoveToCsegment[2].h, segment[0].v); 


for ( s = 1; s <= SEGMENTS ; ++s ) ( 
if С segment[s].h != segmentis - 11.Һ || 
segment[s].v != segmentis - 11.v ) ( 
LineTo(segment[s].h, segment[s].v); 


) 
) 


/* 

хх CurveLauer.c 

** These routines provide a layer of support between my bare- 
bones application skeleton and the Bezier curve code. 
There's little here of interest outside of the mouse 
trecking end the curve drawing. 

** David W. Smith 

*/ 


#include “QuickDraw.h” 
#include “MacTupes.h” 
#include “FontMor .h^ 

"include “WindowMor .h"^ 


* include 
t include 
include 
* include 
* include 
* include 
8S include 
include 


*MenuMgr .h^ 
*TextEdit.h^ 
*DialogMgr.h^ 
*EventMgr .h^ 
*DeskMgr .h^ 
*FileMgr.h^ 
*ToolboxUtil.h^ 
*ControlMgr .h^ 


/* 

* Tracker objects. 
much simpler. 

x 


Similar to MacAPP trackers, but much, 


struct Tracker 


void (*track)(); 
int thePoint; 


static struct Tracker аТгаскег; 
static struct Tracker bTracker; 


/* 
* The Bezier curve control points. 
х/ 

Point 


сопіго1141 = ((144,72), (72,144), (216, 144}, 
(144,216)); 


/* 
* Draw 
* Called from the skeleton to update the window. 
initial curve. 
*/ 
Draw() 
( 


Draw the 


PenMode(patXor2; 
DrawTheCurveCcontrol, true); 
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/* 
* DrawTheCurve 
* Draw the given Bezier curve in the current pen mode.Draw 
the control points if requested. 
*/ 
DrawTheCurve(c, drawPoints) 
Point cl); 


if ( drawPoints ) 
DrawThePoints(c); 
BezierCurveCc[0], c[1), c[2], c[3]); 


/* 
* DrawThePoints 
* Draw all of the control points. 


x/ 
DrawThePoints(c) 
Point с(]; 
int n; 


for Сп= 0; п 4; +) ( 
DrawPoint(c, п); 


) 


/* 

* DrawPoint 

* Draw a single control point 
*/ 


DrawPoint(c, п) 
Point c[]; 
int n; 


PenSize(3, 3); 
Movelo(c[n].h - 1, c[n].v - 1); 
LineToCc[n].h - 1, c[n].v - 1); 
PenSize(1, 1); 


) 
/* 
х GetTracker 
* Produce a tracker object 
* Called by the skeleton to handle mouse-down events. 
x 


If the mouse touches a control point, return a tracker for 
that point. Otherwise, return a tracker that drags a gray 
rectangle. 
*/ 


struct Tracker * 


GetTracker(point) 
Point point; 
void TrackPoint(), TrackSelect(); 


int i; 
aTracker.track = TrackPoint; 


for (C i=0; 104; +i )( 
if С TouchPointCcontrol[i], point) ) ( 
aTracker.thePoint = i; 
return (&aTracker); 


bTracker.track = TrackSelect; 
return C(&bTracker?); 
\ 

/* 

ж TouchPoint 

* Do the points touch? 

*/ 
"define abs(a) (a < Ø ? -(a) : (a)) 


S1 


TouchPoint(target, point) 


Po 
Po 


( 
Su 


if ( abs(target.h) < 3 && abs(target.v) < 3 ) 


re 


/* 


x 


* Called while dragging a control point. 


*/ 
void 


int target; 
int point; 
bPtCpoint, &target); 


return (1); 
turn (0); 


TrackPoint 


TrackPointCtracker, point, phase) 


struct Tracker 
Point point; 
int phase; 
( 
Point savePoint; 


switch ( phase ) ( 
case 1: 


ca 


/* drag - undraw the original curve and draw the new one */ 


са 


) 
/* 


* 

* 
*/ 
stat 
stat 


void 


/* initial click - XOR out the control point */ 
DrawPoint(control, tracker-> thePoint); 


break; 
se 2: 


*tracker ; 


DrewTheCurveCcontrol, false); 


control[tracker-»thePoint] = point; 


DrawTheCurveCcontrol, false); 


break; 
se 3: 


/* release - redraw the control point */ 
DrawPoint(control, tracker-?thePoint); 


break; 


TrackSelect 


Track a gray selection rectangle 


ic Point first; 
ic Rect r^ 


TrackSelect(tracker, point, phase) 
Struct Tracker 
Point point; 
int phase; 


switch ( phase ) ( 
case 1: 


PenPat(gray); 
first = point; 


*{гаскег; 


SetupRect(&r, first, point); 


FrameRect(&r ); 
break; 


case 2: 


FrameRect(&r); 


SetupRect(&r, first, point); 


FrameRectC&r ); 
break; 


case 3: 


/* 
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FrameRect(&r ); 
PenPat(b lack); 
break; 


* SetupRect 


* Setup 
*/ 
"define m 


the rectangle for tracking. 


in(x, y) (((x) < Cyd) ? (x) : Cyd) 


"define max(x, у) (((x) > Cyd) ? (x) : Cyd) 


SetupRect(rect, pointl, point2) 


Rect *rect; 
Point pointi; 
Point point2; 
SetRect(rect, 


minCpointi.h, point2.h), 
min(pointl.v, point2.v), 
maxCpointl.h, point2.h), 
max(pointl.v, point2.v)); 


/* 

xx Skele 

жж This 
Other 


ton.c - A bare-bones skeleton. 
has been hacked up to demonstrate Bezier curves. 
than the tracking technique, there’s little here of 


interest. 


** David 
*/ 


* include 
t include 
include 
t include 
include 
include 
®include 
"include 
"include 
"include 
® include 
* include 


W. Smith 


"QuickDraw.h^ 
“MacTypes .h^ 
"FontMgr .h” 
“WindowMgr .h” 
“MenuMgr .h^ 
“TextEdit .n” 
*DialogMgr.h^ 
“EventMgr .h^ 
“DeskMgr .h^ 
*FileMgr.h"^ 
*ToolboxUtil.h^ 
*ControlMgr.h^ 


WindowRecord wRecord; 


WindowPtr 
/* 


* main 
* [niti 


myWindow; 


alize the world, then handle events until told to 


InitGraf C&thePort); 
InitFontsC); 
FlushEventsCeveryEvent, 0); 
InitWindows(); 

InitMenus(); 
InitDialogs(@L); 
InitCursor(); 
MaxApp | Zone(); 


SetupMenus(); 
SetupWindowC); 
SetupBez ier(); 


while € DoEventCeveryEvent) ) 


М 


) 


/* 


* SetupMenus 
* For the purpose of this demo, we get somewhat non-standard 
and use no menus. Closing the window quits. 


k 


SetupMenus() 
( 


DrawMenuBar ( ); 
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) 


/* 
Ж SetupWindow 
* Setup the window for the Bezier demo. 


Жү. 
а 
Кесі bounds; 


bounds = WMgrPort-?portBits.bounds; 
bounds.top += 36; 
InsetRectC&bounds, 5, 5); 


myWindow = NewWindow(&wRecord, &bounds, “\pBezier Sampler - 
Click and Drag", 1, noGrowDocProc, 01, 1, 01); 


SetPort(inyWindow); 


/* 
* DoEvent 
* Generic event handling. 
*/ 
DoEvent CeventMask ) 
int eventMask ; 


EventRecord  myEvent; 
WindowPtr whichWindow; 
Rect r; 


SustemTask(); 
d ( GetNextEventCeventMask, &myEvent) ) 


(om С myEvent.what ) 


case mouseDown: 
Switch С FindWindowC myEvent.where, &whichWindow ) ) 


case inDesk: 
break; 
case inGoAway: 
( С TrackGoAway(myWindow, muEvent.where) ) 


HideWindow(muWindow); 
return (0); 


break; 
case inMenuBar: 
return (DoCommand(MenuSelect(muEvent.where))); 
case inSusWindow: 
SustemClick(&muEvent, whichWindow); 
break; 
case inDrag: 
break; 
case inGrow: 
break; 
case inContent: 
DoContent(&muEvent); 
break; 
default: 
break; ; 


break; 
case keuDown: 
case autoKey: 
break; 
case activateEvt: 
break; 
case updateEvt: 
DoUpdate(); 
break; 
default: 
break; 
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) 
) 
return(1); 
/* 


* DoCommand 
* Command handling would normally go here. 


*/ 
DoCommand(mResult) 
( 1ong mResult; 
int theltem, temp; 


Str255 name; 
WindowPeek wPtr; 


theItem = LoWord(mResult); 
e С HiWordC(mResult) ) 
) 


HiliteMenuC0); 
return( 1); 


) 


/* 
ж DoUpdate 

* Generic update handler. 
*/ 

T, 


BeginUpdate(muWindow); 
Draw(); 
EndUpdate(muWindow); 


/* 

* DoContent 

* Handle mouse-downs in the content area by asking the 
application to produce a tracker object. We then call the 
tracker repeatedlu to track the mouse. This technique came 
originallu (as nearlu as I can tell) from Xerox, and is used 
in a modified form in MacApp. 

"I 

Struct Tracker 


int (*Track)(); 
); 


int 

DoContent(pEvent) 
EventRecord *pEvent; 

struct Tracker *GetTracker(); 

struct Tracker *t; 

Point point, newPoint; 


* 


point = pEvent- where; 
Global ToLocal(&point); 
t = GetTracker(point); 
if Ct) ( 
(*t->Track)(t, point, 1); 
while С StillDownO ) ( 
GetMouseC&newPo int); 
if € newPoint.h != point.h || newPoint.v != point.v 2 ( 
point = newPoint; 
(Kt Track)Ct, point, 2); 


) 
Ctt» TrackXCt, point, 3); 


== 
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C Workshop 


Event Simulator 


[Matthew Snyder has a B.S.E.E. and a B.S.(Mathematics) 
from the University of Notre Dame. Upon graduation, He was 
commissioned an Ensign in the U.S. Navy Civil Engineer Corps 
and is serving as a construction contract administrator in a field 
office at Mare Island Naval Shipyard in Vallejo, California 
(North Bay area).] 

Introduction 

There are several products available today (including the 
newest system software) which let you play back arbitrary 
sequences of keyboard and mouse events at the touch of a button, 
and which can save you lots of time and effort if you need to 
execute the same pattern over and over. The playback involves 
a sort of simulation in which it is made to appear to the active 
application that the user is producing the events with his own 
fingers. 

What I provide in this article is a poor man's event simulator. 
It's a code library, not a macro maker. There is nothing tricky 
about it, and it doesn't violate any rules that I know of. The 
simulator makes it easy for the programmer to place simulated 
events onto the event queue, and the routines called by the event 
simulator are well-documented. 


Background 
The Operating System normally takes input from the user 
andstores events in the event queue, a standard Operating System 
queue. The Toolbox Event Manager in turn takes events from the 
event queue, as well as from other places, and passes them to the 
application in response to GetNextEvent's. My routines simply 
imitate the Operating System by creating event records and 

placing them on the event queue by hand. 


The Demo 

I wrote the library at a time when I had a need for an FKEY 
that would generate a few mousedowns. Having an FKEY that 
produces mousedowns is a little like having one of the commer- 
cial keyboard macro products I mentioned in the first paragraph, 
and in this article I show an example of such an FKEY. However, 
the resulting keyboard macro is not very elegant, it's limited, and 
it's difficult to install and use. 

In fact, I am not really recommending frequent use of such 
an FKEY. I present the FKEY example merely to illustrate a 
possible use for the simulator. I hope that readers can think of 
more creative and less dangerous ways to use the simulator. 


How the Simulator Works 
I chose not to make use of the Toolbox Event Manager's 
journaling mechanism. A look at the documentation in Inside 
Macintosh will reveal that on one hand it is a complicated matter, 
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ee 


Figure 1. THE journal for the elite 


involving the use of device drivers to both record and play back 
an event journal, and on the other hand it is poorly documented. 
I have yet to see a good example of its use. 

Below, I present the C declaration of the data structure used 
to maintain the toolbox event queue. For the Lightspeed C 
system, the declaration is found in <EventMgr.h>: 


typedef struct ЕМЕ 


struct QElem*qL ink; 
int qType; 

int evtQWhat ; 

long evtQ0QMessage; 
long evtQWhen; 
Point evtQWhere; 

int evtQModif iers; 


) RealEvQE1, *RealEvQETPtr; 


When I was implementing FKEY macros, I found it conven- 
ient to place a delay between some events. To do this, I install a 
routine into the VBL task queue that enqueues an event after a 
certain delay. To make it easier to install the routine, I wrote a 
little interface code and placed it in the simulator library. The 
routine is called MakeTimed, and the data structure needed for 
the VBL queue is declared this way in Lightspeed’s 
<VRetraceMgr.h>: 


vee struct VBLTask 


struct QElem *qLink; 


int qType; 
ProcPtr vblAddr; 

int vblCount; 
int vblPhase; 


) VBLTesk , *VBLQE1Ptr; 


Warnings 
I discovered a few other things while making the FKEY 
macros, and a little thought about these things will indicate why 
the use of the simulator in an FKEY is not the greatest idea. An 
FKEY's code segment becomes locked in the heap while it is 
executing, butbecomes unlocked after it completes. If the FKEY 
routine makes use of the MakeTimed function, and places the 
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address of a routine in its code segment onto the VBL task queue, 
it should lock its own segment down. Doing this after the FKEY 
completes is not a simple matter. 

The simulator allocates dynamic memory to hold the data 
structures whose addresses get enqueued to the toolbox event 
queue, so locking the code segment is not usually necessary. If 
you're wondering what happens to the memory that gets 
enqueued to the event queue, I understand because I wondered 
too. I tracked one block, but didn’t learn anything interesting. 
The memory never becomes deallocated, either by the simulator 
or the Operating System. Because it’s allocated in the application 
heap, itreturns to the pool when the application exits, but this may 
be little consolation to you if you want to generate a lot of events. 
A possible solution would be to add a VBL task that tracks the 
blocks and deallocates them when they’ve served their purpose. 
A tracker would add a lot of complexity to the simulator, and is 
left to the reader. 


How the Demo Works 

A few words about the demonstration FKEY and its algo- 
rithm: It's designed for use with pre-Claris MacDraw (I have not 
tested it with the most current version). Its only function is the 
automatic generation of a picture. It does so using a technique for 
drawing lines by generating a mousedown in one location fol- 
lowed by a mouseup in another location. 

I have found that MacDraw is the only software stupid 
enough (or smart enough, I'm not sure which) to be fooled by this 
technique. If you think about it, a line-drawing application 
should probably be tracking the mouse after a mousedown, 
drawing and redrawing the lineuntil the mouse button is released. 
MacDraw has no problem with the mouse action occurring too 
quickly to track. 

The Menu Manager is much too smart to be fooled by the 
technique, so it's impossible to make an automatic menu selec- 
tion unless the item has a command key equivalent. 

A few words about the code itself: If you're wondering how 
Idetermined the global coordinates of each point in the drawing, 
I used Rick Flott's Mouse Position DA, published in MacTutor 
(I have The Complete MacTutor Vol. 2, so I don't know from 
which issue the article came). I used the DA in combination with 
Apple's MouseKeys. 

More about the demo code: An FKEY runs in the context of 
another program, so it cannot have global data of its own. 
However, Lightspeed provides a facility for embedding data at 
the end of the code block, and accessing itas if it were global data. 
It's almost completely transparent to the programmer. You 
simply declare the variables as global, autoinitialize them as you 
would real global variables, and reference them like any other 
variable. Lightspeed uses register A4 to point to the data space, 
and translates any use of the variable into a reference off А4. 

The only explicit action the programmer must make is to 
place the address of the beginning of the data space into A4 before 
using the variables. As I mentioned above, the data is placed at 
the end of the code block. But Lightspeed uses the BEGINNING 
of the code block as a base in its references. For example, if your 
code turns out to take up 100 bytes, the first pseudo-global would 
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be referenced as 100(A4). 

So the address of the beginning of the data space is the same 
as the address of the beginning of the code block, which is the 
same as the dereferenced value of the handle that you would use 
to lock and unlock the block. This value is conveniently passed 
to the code resource when it is called, in register AO. I use the 
macro recommended in the Lightspeed manual for initializing 
and restoring register A4. 


How to Make the Demo Work 

To use the demonstration FKEY , build the project with type 
set to Code Resource. It's 4-character TYPE should be FKEY, 
and its ID should be 8 (or any number you prefer, between 0 and 
9). Use ResEdit or its equivalent to place the FKEY resource of 
the resulting document into a backup copy of MacDraw. Placing 
the FKEY in the application itself is preferred to placing it in the 
System file, since accidentally using the FKEY elsewhere would 
be undesirable. 

Start up MacDraw, and hit command-shift-8. The rest is 
automatic. 


d MakeKey.c 

1 MakeMeuse.e 

Н MakeMouseDown.e 
: MakeMouseUp.c 

Ч MakeTimed.c 


: EvSimulater .lib 
й. МасТгарѕ5 | 


Figure 2. Тһе Projects 


/EXXXXXXXXKXKXXXKXK 


** MakeKeu.c ** 
XXXXXXXXXXxXXxxx/ 


8include «0SUtil.h» 
8include «EventMgr .h» 


MakeKey(Code Mods) 
int Code, Mods; 

( 

/* locals */ 


EvQETPtr MyEventPtr; 
QHdrPtr TheHdr; 


/* begin executable */ 

/*1: Key Down */ 

MyEventPtr = (EvQETPtr) NewPtr С sizeof (EvQE1) ); 
TheHdr = GetEvQHdr C); 
MyEventPtr->qType = evType; 
MyEventPtr-revtQWhat = 3; 
MyEventPtr->»evtQMessage = Code; 
MyEventPtr-?evtQWhen = TickCount(); 
MyEventPtr->evtQWhere.h = 200; 
MgEventPtr-?evtQWhere.v = 200; 
MyEventPtr-»evtQModifiers = Mods; 
Enqueue (MyEventPtr, TheHdr); 

/*2: Key Up */ 
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Enqueue (MuEventPtr, ТһеНдг); 
/*** For most applications, Keu Up is unneeded *** 


) 
MyEventPtr = (EvQEIPtr) NewPtr С sizeof (EvQE1) ); 

/*kAXXXXXXXXXXXXXXXKEK 
MyEventPtr->qType = evType; ** MakeMouseUp.c ** 
MyEventPtr->evtQwhat = 4; ЖЖАХЖЖЖЖАЖЖЖЖХЖЖЖЖЖЖЖЖ / 
MyEventPtr- evtQMessage = Code; 
MyEventPtr-»evtQWhen = TickCount(); *$include «0SUtil.h» 
MyEventPtr->evtQWhere.h = 361; ®include <EventMgr .h> 
MyEventPtr->evtQWhere.v = 98; 
MyEventPtr->evtQModifiers = Mods; /* mouse up, no key modifier */ 
Enqueue (MyEventPtr, TheHdr ); MakeMouseUpChznt1, vr tcl) 


int hzntl,vrtcl; 
xxx For most applications, Key Up is unneeded ***/ 


) MMUmodChznt1 , vrtc1,9); 
/YYXXXXXXXXXXXKXXKEK ) 

** MakeMouse.c ** 

XXXXXXXXXXKXXXEXKK / /* mouse up with keu modifier */ 
MakeMouse(hzntl],vrtc1) MMUmod(hzntl1,vrtc],mod) 

int hzntl,vrtcl; int hzntl,vrtcl,mod; 

( 
MakeMouseDownChznt]l, vrtcl); /* locals */ 


MakeMouseUp(Chznt]l, vrtel); 
EvQEIPtr MyEventPtr; 


) QHdrPtr TheHdr; 

/®*ЖХЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖХХ /* begin executable x / 

** MakeMouseDown.c ** 

XXXXXXXXXXXXXXXXXXXXX / MyEventPtr = CEvQE1Ptr) NewPtr С sizeof (EvQE1) 2; 
include «0SUtil.h» TheHdr = GetEvQHdr(); 


include <EventMgr.h> 
MyEventPtr->qType = evlupe; 


/* mouse down, no key modifier */ MyEventPtr-?evtQWhat = 2; 
MyEventPtr->evtQMessage = 0; 

MakeMouseDown(Chznt1, vr tcl ) MyEventPtr-»evtQWhen = TickCount(); 

int hzntl,vrtcl; MyEventPtr->evtQWhere.h = hzntl; 

( MyEventPtr-»evtQWhere.v = vrtcl; 


MyEventPtr->evtQModifiers = mod; 
MMDmodChznt1,vrtcl,8); 


Enqueue (MyEventPtr, TheHdr); 
) 


) 
/* mouse down with key modifier */ 

/ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
MMDmodChznt1,vrtcl,mod) ** MakeTimed.c ** 
int hzntl,vrtcl,mod; ыы ыы SSR ERS EEE 


®include <050411.һ» 


/* locals */ Binclude «VRetraceMgr .h? 
EvQEIPtr MyEventPtr; MakeTimed(Func, Ticks) 
QHdrPtr TheHdr; ProcPtr Func; 

int Ticks; 
/* begin executable */ 
MyEventPtr = CEvQE1Ptr) NewPtr С sizeof CEvQET) 2; /* locals */ 
TheHdr = GetEvQHdr (C); VBLQEIPtr MyVBLptr; 
MyEventPtr->qType = еуТуре; /* begin executable */ 
MygEventPtr-?evtQWhat = 1; 
MyEventPtr->evtQMessage = 0; MyVBLptr = € VBLOEIPtr ) NewPtr С sizeof( VBLTask ) ); 
MyEventPtr-?evtQWhen = TickCount(), 
MyEventPtr-?evtQWhere.h = hzntl; MyVBLptr->qType = уТуре; 
MyEventPtr-?evtQWhere.v = vrtel; MyVBLptr-?vblAddr = Func; 
MyEventPtr-»evtQModifiers = mod; MyVBLptr-?vblCount = Ticks; 


MyVBLptr-?vblPhase = 0; 
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VInstall (MuVBLptr); 
) 


[/**Xxxxxxxxxx 


xx demo.h ** 
XXXXKXXXXXXXK / 


/* struct for handling large sets of points */ 


typedef struct letter ( 
int *h; 
int Ху; 
) letter; 


/* functions used to get access to psuedo-globals */ 


"define SetUpA4C) asm ( MOVE.L A4, -CSP)\ 


MOVE.L AQ, A4 ) 
"define RestoreA4C) asm ( MOVE.L СР )+, A4 ) 


[XX **x xxx xxx 


xk demo.c ** 
KKK AKA 5554) 


#include “demo.h” 


/* psuedo-global data points */ 


int баба! 1201 


int data2 1201 = ( 115, 187, 187, 151, 169, 151, 187, 187, 115,115, Ø 
int data3 [201 = ( 155, 155, 164, 164, 173, 173, 182, 182, 155, Ø, 
164,173, 0 ); 

int data4 [20] = ( 160, 187, 187, 178, 178, 187, 187, 160, 160, 0, 
169, 169, 0 ); 

int data5 [20] = ( 182, 182,209,209, 191, 191,209,209, 182, Ø ); 
int data6 [20] = ( 160, 187, 187, 178, 178, 169, 169, 160, 160, Ø ); 
int data7 1201 = ( 200,200, 209,209,227, 227,236,236, 200, Ø ); 
int data8 1201 = ( 115, 142, 142, 187, 187, 142, 142, 115, 115, Ø ); 
int data9 1201 = ( 227,227,254, 254,245, 245,236, 236,227, 0 ); 
int datalü [20] = ( 160, 187, 187, 160, 160, 178, 178, 160, 160, 0); 
int datall [20] = ( 254,254, 263,263, 272,272,281,281,254, 0 ); 
int data12 [20] = ( 160, 169, 169, 187, 187, 169, 169, 160, 160, 0 ); 
int data13 [20] = ( 281,281,308,308,281, Ø, 

2909,290,299, 299,290, 0 ); 

int datal4 [20] = ( 160, 187, 187, 160, 160, Ø, 

169, 178, 178, 169, 169, 0); 

int datal5 (20) = ( 308,308,317,317,335,326,335,335,308, 0, 
317,326, Ø ); 

int datal6 [20] = ( 160, 187, 187, 179, 187, 178, 178, 160, 160, Ø, 


169,169, 0); 

/* main routine */ 
mainO { 

/* locals */ 


letter M, a, c, T, u, t, o, r; 
int h_index, v_index; 


/* begin executable code */ 
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( 119,119, 128, 128, 137, 146, 146, 155, 155, 119, Ø 


/* access psuedo-globals */ 
SetUpA4(); 


/* load structures */ 


M. 
a. 
c. 
1s 
u. 
t. 
o 

r 


> > > > > > > = 


= datal4; 
= data!6; 


3 O ec 400 = 
< < < < < < < < 

" 

а. 

m 

cr 

о 

eo 


/* select from pallette */ 
MakeMouse( 15, 100); 


/* draw letters */ 

DrawLetter(M.h, M.v); 

Drawletter(a.h, a.v); DrawLetter(&a.hL 10], ka.v[10]); 
DrawLetterCc.h, c.v); 

DrawLetter(T.h, T.v); 

DrawLetter(u.h, u.v); 

DrawLetter(t.h, t.v); 

DrawLetter(o.h, o.v); DrawLetter(&o.h[6], ko.v[6]); 
DrawLetter(r.h, r.v); DrawLetter(&r.h[10], &r.v[101); 


/* deselect last line */ 
MakeMouse(400, 250); 


/* pop A4 */ 
RestoreA4(); 


) 

/* routine to draw letters */ 

DrawLetter ( hArrau, vArray ) 

int hArrau[], уАггауГ1; 

( 

int h_index, v_index; 

for (h_index=0,v_index=0; (hArrau[h_index+1] != 0) || 
(vArrau[v_index+1] != 0) ; h_index++, v_index++) ( 


MMDmod(hArrau[h_index], vArraylv_index], 0x0100); 
MMUmod(hArrau[h_index+1], vArraylv_index+1], 0х0100); 
) 
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How to Write a Spreadsheet in LS C 


Bryan Waters is a Software Engineer for Maynard Electron- 
ics, and is currently working as part of a team to develop a finder- 
like tape backup system. 


Dear Cary Mariash 

In the January '88 issue of MacTutor, a letter sent by Cary 
Mariash requested information on Macintosh tools to create 
spreadsheet type windows. MacTutorCalc is an example of a 
simple (very simple!) spreadsheet type application, that uses the 
List Manager ( IM - IV ) to create it's windows. (Note: MacTu- 
torCalc is written in Think C 3.0, see the project window in figure 
1) 

List Manager in action! 

The call to Lnew is used to create the list (figure 2). The 
dataBounds parameter is set to have an extra row and column 
than our work area. This, of course, is to support the row and 
column headers. After the list has been created the programmer 
has several more options, involving selection, and installing a 
routine in the IClikLoop field to be called repeatedly while 
LClick has control. The selFlags field of the list handle allow 
complete customization of the selection algorithm used by the 
list manager. MacTutorCalc is content to use the default selec- 
tion, but when we call LClick to handle our mouseDown events 
in the window, any scrolling causes the spreadsheet to scroll, 
without the grid being updated. To fix this, MacTutorCalc 
installs a IClickLoop routine to update the grid continuously 
during calls to LClick. This works great, except the List Manager 
does not call this routine when the mouse button is pressed in the 
scroll bars, so that the grid is updated then only after the mouse 
button is released. Although it is not implemented here, this 
could be fixed by installing a pointer to our grid routine in the 
system global DragHook ( $9F6 ) which is called by Drag- 
GrayRgn. Since the control manager routine TrackControl calls 
DragGrayRgn to drag the outline of the scroll bars thumb button, 
this would achieve the desired effect. 

There are other points to take into account when using a 
window such as this. For example, when the user resizes the 
window, it would not be desirable to allow the user to size the 
window out of alignment with the cell boundries simply because 
it looks bad. To handle this, after the call to GrowWindow, we 
make sure that the new size is a multiple of the cell size. Updating 
is handled almost completely by the list manager routine LUp- 
date, although we still have to draw the grid, and the grow icon. 

Data entry is probably where MacTutorCalc could be im- 
proved the most. Currently data entry is implemented by double- 
clicking on the desired cell ( LClick returns TRUE when a cell 
was double-clicked and a call to LLastClick is used to get the 
cell's address). This brings up a dialog prompting for the data. 
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Project Sourc 


e Windows 
— : MacTutorCalc 


* DrawGrid.c 

о EntrData.c 

* functions.c 

ө MacCalc.c 
MacTraps 

Ф Parser.c 

Ф SetType.c 


Math 
stdio 


In an application intended for serious use, this would get ex- 
tremely tiring. Thiscould be fixed by adding a data entry window 
at the top of the screen ( Excel Style ) and allowing the user to 
enter data into the currently selected cell through this window. At 
this point we have data that needs to processed, so we determine 
the type of data ( formula, or string ) and then set our calculation 
flag. The routine DoCalc is called in response to this, and 
processes the whole spreadsheet, calling the parser for formula, 


é File Edit 


9909900000000000000009000000400000000000000000 о 9 090004909000000900000000 000000000009 000000000000 6006060060000 006900999000 


sesoosoossseacosssss 922000040005 ееегееееееесе»» 00900540 0200000000090000 0000009 00000009 Ee 00900900000 0000000090000 000 0099005 i mtis 

M UN ee ge Er EIU AVR ENCORE DUO IA AD AT aS MET T VAR ww O09 7 5 B ^ || - 
H е ЕИ 

NE СРЕ СТС зонани И АБЫ 


000120000000060060000 000000000000 000000ооовоое ге. 
3 2 
Е----.-:еееееесесееее»......%24%есегесеееесеее:)2%%9%%%%%есесегееесееее40%%%4%%4%»өе0000еөөөө ааа оао заново 
00000000000000000000 9025 9005920:000000000000096 


т ааа 


PODRRREBRARRRRAARRARAARRARRARR 
Hi 


HESSB8888588888858888888858389 ШЕШЕННІҢ 


Enter data: 


Figure 2. Spreadsheet & Dialog Entry 
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and ignoring strings. After the data has been parsed, LSetCell is 
used to put the data into the list. Alternatively, if the cell has been 
blanked out, then LCIrCell is used to clear the data. 


About MacTutorCalc... 

MacTutorCalc is a simple spreadsheet written for the pur- 
pose of demonstrating use of the list manager. The work area for 
our application is set to 8 columns by 8 rows. It is capable of 
accepting both strings and formulae, and constants. Data is 
entered into a cell by double-clicking on it. I know that this is 
awkward, but other methods would have unnecessarily compli- 
cated this example. Any data entered into a cell that starts with 
“=” is considered a formula and will be parsed, and any number 
will be treated as a constant, everything else is considered a 
string. A formula can be any simple algebraic expression, using 
floating or absolute cell addresses. There a few simple functions 
in MacTutorCalc that use the Math library distributed with Think 
C. In the future, we could expand our spreadsheet to include: 

* ability to save and retrieve spreadsheets 

* a full function library 

* cell formatting and spreadsheet editing features 

* memory paging system to support larger spreadsheet sizes 

° support for SYLK format 

[There is a known bug in the text to binary conversion 
routines. Apple's conversion routines were used, and so large 
formatted numbers will not be converted to text correctly. Note 
also that Apple frowns on trying to use the List Manager to write 
the next Excel Product, so if you get serious about this project, re- 
write it without using the List Manager. -Ed] 

Listing: CalcData.h 


/* Global data */ 
extern int quit flag ; 


extern Rect minmax.size ; 

extern Rect curr.screen ; 

extern int automatic.calculation ; 
extern int calc.data ; 

extern int do.calc.now ; 

extern SHEET. WIN.PTR curr-sheet ptr ; 
extern SHEET. WIN-HDL calc hdl ; 
extern FUN_ENTRY fun_tablel) ; 

extern ARG arg_free_pooll ) ; 


Listing: MacCalc.h 


Binclude «МасТурев.һ» 
®include <ListMgr .h> 
®ifndef NULL 

define NULL OL 


#endif 

Sdgef ine MAX_ROWS 8 
®def ine MAX. COLUMNS 8 
define CELL WIDTH 96 
def ine CELL. HEIGTH 16 
#def ine ENTER.DATA. DIALOG 128 
def ine APPLE. MENU 1 
#def ine FILE. MENU 256 
#def ine EDIT. MENU 251 


/* Types for cell */ 
define CLEARED =1 
8Sdef ine UNDEFINED 0 
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"igef ine STRING 1 
"tdef ine FORMULA 2 
#def ine CONSTANT 3 


struct cell.struct( 
int type ; 
double value ; 
Str255 formula ; 


) 


typedef struct cell_struct CELL, *CELL PTR, **CELL_HDL ; 


struct sheet. win( 
WindowPtr sheet window. ptr ; 
ListHandle sheet list hdl ; 
CELL sheet. data( MAX. ROWS ] [MAX_COLUMNS] ; 


2 


typedef struct sheet_win SHEET_WIN, *SHEET_WIN_PTR, 
*XSHEET_WIN_HDL ; 


/* Argument types */ 
8define VALUE_ARG 1 
"def ine STRING_ARG 2 

/* Arg usage defines */ 
8define IN.USE TRUE 
#def ine FREE ARG FALSE 


struct fun. arg( 
struct fun. arg *next arg ; 
int in_use ; 
int type ; 
double value ; 
5іг255 string ; 


typedef struct fun_arg ARG, *ARG.PTR, **ARG_HDL ; 
struct fun_entry{ 

char fun name[32] ; 

double (*fun_ptr)( ) ; 
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typedef struct fun_entry FUN-ENTRY, *FUN_ENTRY_PTR, 
**FUN_ENTRY_HDL ; 


/* Prototupes */ 

int Dolnit( void ) ; 

void DoEventLoop( void ) ; 

void DoActivateC EventRecord * ) ; 
void DoUpdateC EventRecord * ) ; 
void DoMouseDown( EventRecord * ) ; 


int ClikLoop( void ) ; 
void EnterData( Cell, SHEET. WIN.HDL ) ; 
void DoCalc( SHEET. WIN HDL ) ; 


Listing: SheetHndlg.h 

/* SpreadSheet Handling prototypes */ 
int OpenNewSpreadsheet( char * ) ; 
int Огажбгіас WindowPtr ) ; 

Listing: Parser.h 


/* Parse errors */ 


Rdef ine MISMATCHED. PARENTHESIS 200 
8def ine INVALID. NUMBER 201 
8def ine INVALID. ADDRESS 202 
#def ine ADDRESS. TOO. LARGE 203 
"def ine INVALID. FUNCTION 204 


/* Prototypes */ 
void SetTgpeC CELL_PTR, int 2 ; 
double ParseFormulaC unsigned char *, int х ) ; 
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double ParseExpression( void ) ; ( NULL, FREE_ARG, 0, 0, 0 ), 
double ParseFactor( void ) ; ( NULL, FREE_ARG, 0, 0, 0), 
double ParseValue( void ) ; (NL  €REE.ARG, 0, Ø, 0), 
double ParseAddress( void ) ; ( NULL, FREE_ARG, 0, 0, 0 ), 
define IsDigit(x) (C(x)<=’9') && ((x))=°'0')) ( NULL, FREE. ARG, 0, 0, 0 ), 
"define IsAlpha(x) С C C (x) ›= ‘A’ 2 && C (x) <= 2? 2 ) || € ( NULL, FREE. ARGC, 0, 0, 0), 
C (x) >= fa’ ) && C OO <= “Z? 22D ( NULL, FREE_ARG, 0, 0, 0 ), 
int IsFunction( void ) ; { NULL, FREE_ARG, 0, 0, 0 }, 
int GetRowC void ) ; ( NULL, FREE. ARG, 0, 0, 0), 
int GetColumn( void ) ; ( NULL, FREE. ARG, 0, Ø, Ø ), 
double CallFunctionC ) ; ( NULL, FREE_ARG, 0, 0, 0), 
int LookupC unsigned char * ) ; ( NULL, FREE. ARGC, 0, 0, 0), 
ARG_PTR BuildArg( void ) ; ( NULL, FREE_ARG, 0, 0, 0), 
double atof( void ) ; ( NULL, FREE. ARG, 0, 0, 0), 
void ftoaC double, unsigned char * ) ; ( NULL, FREE. ARG, 0, 0, 0 ) ); 
double GetFloat€ unsigned char *, int х ) ; 
ARG_PTR GetArg( void 2 ; Listing: DoActivate.c 
void PutArgC ARG_PIR ) ; 
void DestroyArgs( ARG_PTR ) ; *include «WindowMgr .h> 
®include <ListMgr .h> 
Listing: CalcData.c "include «OSUtil.h» 
8include «EventMgr .h> 
Sinclude «WindowMgr .h? 
®include «ListMgr .h? "include *MacCalc.h"^ 
*Sinclude «0SUtil.h» ®include "SheetHndlg.h" 
*include «EventMgr .h> * include “CalcData.h” 
include “MacCalc.h” void DoActivateC ev ) 
®include "SheetHndlg.h"^ EventRecord *ev ; 
/* Global data */ WindowPtr curr_window_ptr ; 
int quit flag = FALSE ; SHEET_WIN_HDL sheet record. hd] ; 
int activate ; 
/* Grow window limits */ 
Rect minmax_size ; activate = ev- modif iers&0x0001 ; 
/* Current screen size */ 
Rect curr_screen ; /* Get spreadsheet hdl */ 
curr_window_ptr = (WindowPtr)ev- message ; 
/* do calculation switches */ sheet record .hdl = (SHEET_WIN_HDL )GetWRefCon( 
int automatic.calculation = TRUE ; curr.window.ptr ) ; 
int calc_data = FALSE ; 
int do_calc_now = FALSE ; /* Do list activation or deactivation */ 
LActivateC activate, (**sheet record hdl2.sheet list hdl2; 
/* Current spreadsheet globals */ return ; 


SHEET. WIN.PTR curr-sheet ptr ; 
SHEET. WIN.HDL calc.hdl ; 


Listing: DoCalc.c 
extern double fsumC ), fabsoluteC 2, fmodulusC ), fsqrt(C ) ; 


8include «WindowMgr.h? 


/* Function table */ 8include <ListMgr .h> 

FUN_ENTRY fun_table[] = ( "include <0SUtil.h? 
/* Standard math functions */ ®include «EventMgr .h» 
( “SUM”, fsum ), 
( “ABS”, fabsolute ), include “MacCalc.h” 
( “MOD”, fmodulus ), include "CalcData.h" 
( EE. fsqrt ), "include "Parser.h"^ 
(0 ; 


void DoCalc( sheet_record_hdl 2 
ARG arg-free_poo1[30] = ( SHEET_WIN_HDL sheet_record_hd1 ; 
( NULL, FREE_ARG, 9 ( 

( NULL, FREE_ARG, 0 
( NULL, FREE_ARG, 0 
( NULL, FREE_ARG, 0 
( NULL, FREE_ARG, 0 
( NULL, FREE_ARG, 0 
( NULL, FREE_ARG, 0 
( NULL, FREE_ARG, 0 
0 

0 

0 

0 

0 

0 

0 


` 
` 


int i, j ; 
Str255 buffer ; 
Cell curr.cell ; 
int error ; 
char *err.mess ; 


` 
` 


` ` 
` ` 
` ` ` ` 


` 
` 
` 


` 
` 
` 


` 
` 


/* Lock and dereference the handle */ 
HLockC (Handle)sheet-record-hdl ) ; 
curr_sheet_ptr = *sheet record hdl ; 


( NULL, FREE. ARG, 
( NULL, FREE. ARG, 
( NULL, FREE. АРС, 
( NULL, FREE_ARG, 
( NULL, FREE_ARG, 
( NULL, FREE_ARG, 
( NULL, FREE_ARG, 


` 
` 


` 
` 


` 
` 


/* Process all cells */ 
forC i=0;icMAX_ROWS;i++ ) ( 
for( 3-0; j<MAX_COLUMNS; j++) ( 
switch( curr_sheet_ptr->sheet_datalil{j].type ) ( 


` 
` 


` 
` 


` 
` 


ч? чы? — — чы? чы? Senge er  . v. See Se 


мым www o ` ` Мм ` м ` 


` 

© = < = = = = = = = = = = & 
` 

a © =< = = = = = = = = G = Q сы 
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` 
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/* If cell tupe is undefined then do nothing */ #include «0SUtil.h» 


case UNDEFINED: ®include <EventMgr .h> 
break ; 
/* If cell type is undefined then clear cell */ ®include “MacCalc.h” 
case CLEARED: ®include “SheetHndlg.h* 
SetPt( &curr_cell, ј+1, 1+1 ) ; 8include “CalcData.h” 
LClrCellC curr_cell, curr_sheet_ptr- 
^sheet list hdl ) ; void CreateMenus( void ) ; 
curr.sheet ptr-^?sheet data[il[jl.tupe = 
UNDEFINED ; int DoInitC ) 
break ; 
/* If cell type is string, put string in cell */ 
case STRING: /* initialize all the MacIntosh Managers */ 
SetPtC &curr.cell, ј+1, 1+] ) ; InitGrafC C Ptro&thePort ) ; /* initialize quickdraw */ 
LSetCellC &curr. sheet. ptr- InitFontsC 2; /* initialize the font manager */ 
»sheet_datalil(j).formulal1), InitWindows€ ) ; /* initialize the window manager */ 
curr_sheet_ptr- InitCursor( ) ; /* initialize the cursor */ 
"sheet. dataLi1LjJ.formula[0], InitMenus( ) ; /* initialize the menu manager */ 
curr. cell, TEInitC ) ; /* initialize the text edit manager */ 
curr.sheet.ptr-?sheet list hdl ) ; InitDialogsC NULL ) ; /* initialize dialog manager */ 
break ; 
case CONSTANT: /* Flush events */ 
SetPtC &curr_cell, j*1, i+1 ) ; 
curr_sheet_ptr->sheet_dataliJ{j].value = FlushEventsC everyEvent, Ø ) ; 
GetFloatC curr_sheet_ptr- 
»sheet_datalil(j].formula, &error ) ; /* Get curr screen size */ 
ifC error ) ( curr_screen = screenBits.bounds ; 
AlertC error, NULL ) ; SetRect( &minmax_size, 207, 77, 447, 159 ) ; 
err.mess = "WMp***ERRORX**X^ ; 
LSetCellC err_mess+1, Хегг. mess, /* Expand heap to maximum and allocate more masters */ 
curr_cell, curr.sheet ptr-»sheet list hdl ) ; MaxApplZone(C ) ; 
}е15е{ MoreMasters( ) ; 
ftoaC curr_sheet_ptr- MoreMasters( ) ; 
»sheet_datalil{j].value, buffer ) ; MoreMasters( ) ; 
LSetCell(€ &buffer[1], MoreMasters( ) ; 
buffer (01, MoreMasters( ) ; 
curr.cell, 
curr.sheet.ptr-?sheet list.hdl ) ; CreateMenus( ) ; 
break ; OpenNewSpreadsheet( “\pUntitled” ) ; 
/* Parse formula then convert value to string and ) 
put in cell */ void CreateMenus( ) 
case FORMULA: 
SetPt( &curr cell, ј+1, itl); MenuHandle menu ; 
curr_sheet_ptr->sheet_datalil{j].value = 
ParseFormula( curr_sheet_ptr- menu = GetMenuC 1); 
»sheet_datalil[j].formula, &error ) ; AddResMenu( menu, 'DRVR' ) ; 
if€ error ) ( InsertMenuC menu, 0 ) ; 
Alert( error, NULL ) ; InsertMenuC GetMenuC 256 ), 0); 
err.mess = “\p***ERROR***” > InsertMenuC GetMenu( 257 2,0); 
LSetCellC err_mess+1, *err. mess, DrawMenuBar( ) ; 
curr.cell, curr. sheet ptr- sheet list hdl ) ; ) 
Jelse ( 
ftoaC curr_sheet_ptr- Listing: DoMouse.c 
»sheet_datalil{j].value, buffer ) ; 
LSetCellC &buffer[1], include «WindowMgr.h» 
buffer[0], 8include «ListMgr.h» 
curr_cell, 8include «0SUtil.h» 
curr-sheet.ptr-»sheet list hdl ) ; include <EventMgr .h> 
break ; Sinclude "MacCalc.h"^ 
include "SheetHndlg.h"^ 
| ) ®include “CalcData.h” 
calc_data = FALSE ; WindowPtr curr_window_ptr ; 
DrawGridC curr.sheet ptr-»sheet window.ptr ) ; 
HUnlockC CHandle2sheet record. hdl ) ; void DoMouseDown( ev ) 
return ; EventRecord *ev ; 
) 
SHEET. WIN.HDL sheet. record hdl ; 
Listing: DoInit.c Point new.point ; 
int location ; 
®include «WindowMgr .h» GrafPtr tmp port ; 
8include «ListMgr.h? Rect boundsRect ; 
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long newsize ; 
long menuchoice ; 
int width, heigth ; 
union ( 

long tmp ; 
Cell last_cell ; 
da; 


location = FindWindow(€ ev->where, &curr_window_ptr ) ; 


ifC С curr_window_ptr != FrontWindowC ) ) && (С 


curr_window_ptr != NULL 2 ) ( 
SelectWindowC curr_window_ptr ) ; 
return ; 


new_point = ev- where ; 
GetPort( &tmp_port ) ; 
SetPortC curr_window_ptr ) ; 
GlobalToLocalC &new.point ) ; 


switchC location ) ( 
case inDesk: 
break ; 
case inMenuBar: 
menuchoice = MenuSelect( ev- where ) ; 


ifC HiWordC menuchoice ) == FILE. MENU ) ( 


quit flag = TRUE ; 


HiliteMenuC 0); 
break ; 


cese inConten L sheet. record.hdl = 


CSHEET_WIN_HDL )GetWRefCon(€ curr_window_ptr 2; 
if( LClickC new.point, ev->modifiers, 
(**sheet. record. hdl2.sheet list. hdl 2 ) ( 


a.tmp = LLastClickCC**sheet. record. hdl2.sheet list hdl ) ; 
EnterDataC a.last cell, sheet record.hdl ) ; 


DrawGridC curr_window_ptr ) ; 
break ; 

case inDrag: 
boundsRect = curr.screen ; 


DragWindowC curr_window_ptr, ev-?where, &boundsRect ) 


break ; 
case inGrow: 


sheet record .hdl = (SHEET. WIN. HDL )GetWRef Conc 


curr.window.ptr ) ; 


newsize = GrowWindow( curr_window_ptr, ev->where, 


&minmax_size ) ; 
ifC newsize ) { 


width = € С LoWordC newsize ) / CELL_WIDTH ) * 


CELL_WIDTH ) + 15 ; 


heigth = € С HiWordC newsize ) / CELL_HEIGTH ) * 


CELL_HEIGTH ) + 15 ; 


SizeWindow( curr_window_ptr, width, heigth, TRUE ) 


7 
LSizeC width-15, heigth- 15, 
(**sheet. record. hdl2.sheet. list. hd] 2; 
DrawGridC curr window. ptr 2; 
DrawGrowIcon(C curr window.ptr 2; 
break ; 
case inGoAway: 


if( TrackGoAway( curr-window ptr, evo where 2 2 ( 


quit flag = TRUE ; 
break ; 
T tmp_port ) ; 
return ; 


) 
int ClikLoop( ) 
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DrawGrid( curr_window_ptr ) ; 


return TRUE ; 


Listing: 


include 
include 
include 
t include 


Зілсімде 
tt'include 
8include 


DoUpdate.c 


<WindowMgr .h> 
<ListMgr .h) 
«0SUtil.h» 
<EventMgr .h? 


^MacCalc.h"^ 
“SheetHndlg.h” 
“CalcData.h’ 


void DoUpdate( ev ) 
EventRecord “еу ; 


WindowPtr curr.window.ptr ; 
SHEET.WIN.HOL sheet record hdl ; 


curr.window.ptr = (WindowPtr)ev- message ; 


sheet_record_hd] = (SHEET_WIN_HDL )GetWRefCon( 
curr_window_ptr ) ; 


BeginUpdate€ curr_window_ptr ) ; 


LUpdateC curr_window_ptr->visRgn, 
(**sheet. record hdl).sheet. list hdl ) ; 


DrawGrid€ curr_window_ptr ) ; 
DrawGrowIconC curr_window_ptr ) ; 
EndUpdateC curr_window_ptr ) ; 


return ; 


) 


Listing: 


* include 
#include 


DrewGrid.c 


«ListMgr .h> 
<WindowMgr .h? 


*include <MacTypes.h> 
8include <QuickDraw.h> 


*Sinclude “MacCalc.h” 
"include “SheetHndlg.h” 


int DrawGridC win. ptr 2 
Coo win_ptr ; 
GrafPtr tmp port ; 
Rect win_rect ; 
int bottom ; 
int right ; 
int numh_lines ; 
int num_v_lines ; 
int i, max ; 


GetPortC &tmp_port 2; 
SetPort( win_ptr ) ; 


PenNormal( ) ; 
PenPat( gray ) ; 


win_rect = win_ptr->portRect ; 
bottom = winrect.bottom - 15; 
right = win rect.right - 15 ; 
num_h_lines = bottom / CELL_HEIGTH ; 
num_v_lines = right / CELL WIDTH ; 
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max = C num_h_lines > num. v lines ) ? 
num-h_lines:num_v_lines ; 


for( 


i= 1; i <= max ; it* ) ( 


if( i < nun-h_lines ) ( 


i 


Movelo( 0, i*CELL_HEIGTH ) ; 
LineToC right, i*CELL HEIGTH ) ; 


fC i < num v. lines ) ( 
MoveToC i*CELL_WIDTH, 00; 
LineToC i*CELL_WIDTH, bottom ) ; 


PenNormalC ) ; 
SetPort( tmp.port ) ; 


) 
Listing: 


tinclude 
include 
8 include 
® include 


include 
* include 
"include 
"include 


return ; 


EntrData.c 


«ListMgr .h> 

<DialogMgr .h> 
<MemoryMgr .h? 
(QuickDraw.h> 


*MacCalc.h"^ 
"SheetHndlg.h"^ 
^CalcData.h"^ 
^Parser.h"^ 


"define ENTER.BUTTON 1 
#def ine CANCEL. BUTTON 2 
"def ine DATA. ITEM 4 


void EnterDataC cell, sheet. record.hdl ) 


Cell cell 


д 


"cei sheet.record hd] ; 


DialogPtr new.dialog ; 


int i 
Hand] 
Rect 


tem_hit ; 
e hdl ; 
box ; 


int type ; 
int had_data = FALSE ; 


if€ C cell.v ) != 0 && C cell.h != 0 ) ) { 


HLockC CHandle)sheet_record_hdl ) ; 
new_dialog = GetNewDialog( ENTER_DATA_DIALOG, NULL, 
(WindowPtr)-1L ) ; 


/* Outline button */ 
SetPort( new.dialog ) ; 
GetDItemC new.dialog, ENTER.BUTTON, &type, &hd1, &box) 


PenNormal( ) ; 

PenSizeC 3,3 ) ; 

InsetRectC &box, -4,-4 2; 
FrameRoundRect( &box, 16, 16 2; 


GetDItemC new_dialog, DATA_ITEM, &type, &hdl, &box ) ; 


if€ C**sheet. record hdl2.sheet. data(cell.v-1][cel].h- 
1J.formulat] ! 0 ) ( 


(**sheet. record. hdl)2.sheet. datalcell.v-1][cell.h-1].formula) ; 


) 


SetITextC hdl, 


SellTextC new dialog, DATA_ITEM, Ø, 255 ); 
had.data = TRUE ; 


do( 


ModalDialog( NULL, &item. hit ) ; 


)whileC item hit == БАТА ITEM ) ; 
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ifC item hit != CANCEL. BUTTON ) ( 
GetITextC hdl, 
&C**sheet. record hdl)2.sheet datal[cell.v-1][cel].h-1].formula2; 
SetTypeC &C**sheet. record. hd1).sheet. data[cell.v- 
1}{cell.h-1], had.data ) ; 
calc-hd] = sheet record hdl ; 
calc_data = TRUE ; 


CloseDialog( new dialog ) ; 

HUnlock( CHandle)sheet_record_hdl ) ; 
Jelse( 

SusBeep( 1); 


return ; 


Listing: functions.c 


include «WindowMgr .h? 
8include <ListMgr .h> 
8include <OSUtil.h> 
8include <EventMgr .h> 


®include <Math.h> 


include "^MacCalc.h"^ 
* include *CalcData.h" 
include “Parser .h” 


double fsumC arg ) 
ARG_PTR arg ; 
( 


double value = Ø ; 
value += arg->value ; 


whileC arg->next_arg != NULL ) ( 
arg = агд-› пехі_агд ; 
value += arg-?value ; 


return value ; 


double fabsolute( arg ) 
ARG_PTR arg ; 
( 


register double value ; 


value = arg value ; 
returnC C value >= 0 ) ? value:-value ) ; 


double fmodulus( arg ) 
ARG_PTR arg ; 
( 


register double value! ; 
register double value2 ; 
ARG-PTR curr_arg = arg ; 


valuel = arg->value ; 
value2 = arg->next_arg->value ; 
return( fmodC valuel, value2 ) ) ; 
) 
double fsqrtC arg ) 
ARG_PTR arg ; 
( 


register double value ; 
value = arg->value ; 
return(€ sqrtC value 2); 
) 
Listing: MacCalc.c 


8include «WindowMgr .h»? 
8include «ListMgr .h» 


6 3 


"include «0SUtil.h» int terror ; 
#include <EventMgr .h> 


register double value ; 
*include “MacCalc.h” 
#include “SheetHndlg.h” 
®include *"CalcData.h"^ 
include “parser .h” 


/* convert into c string in buffer */ 
BlockMoveC &formula[2], buffer, formula(801-1 ) ; 
buf fer[formula[ð]-1] = 0 ; /* Ø terminate buffer */ 


mainC ) curr_pos = buffer ; 
parse_err = 0 ; 


DoInitC 2 ; v (С = ParseExpression( ) ; 
DoEventLoop( ) ; 


*error = parse_err ; /* Set error flag */ 


void DoEventLoop( 2 
( return ( value ) ; 
EventRecord ev ; 
double ParseExpression( ) 
while( !quit_flag ) ( 
SustemTask( ) ; 
ifC GetNextEventC everyEvent, &ev 2 ) ( 
SwitchC ev.what ) ( 
case mouseDown: 
DoMouseDown( kev ) ; switchC *curr.pos ) ( 
break ; case ‘+’: 
case mouseUp: curr_post+ ; 


register double val ; 


val = ParseFactor( ) ; 


break ; val += ParseExpression( ) ; 
case keyDown: break ; 
break ; case ‘-’: 
case keyUp: curr_post+ ; 
break ; val -= ParseExpression( ) ; 
case activateEvt: break ; 
DoActivateC &ev ) ; case '*': 
break ; curr_post++ ; 
case updateEvt: val *= ParseExpression( ) ; 
DoUpdate( &ev ) ; break ; 
break ; case ‘/’: 
curr_pos++ ; 
)е1ѕе ( val /= ParseExpression( ) ; 
if€ С automatic.calculation || do_calc_now ) && break ; 


calc.data ) ( 
DoCalcC calc.hdl 2 ; 
do_calc_now = FALSE ; 
calc_data = FALSE ; 


return val ; 


double ParseFactor( ) 


) 
) register double val = Ø ; 
) register double val2 ; 
return ; register int has_sign = FALSE ; 


if€ *curr.pos == '-^ ) ( 
Listing: Parser.c has_sign = TRUE ; 
curr_postt ; 


include <WindowMgr .h> ) 
8include <ListMgr.h> 
#include <0SUtil.h? if( *curr_pos != '(* ) ( 


#include 


«EventMgr .h? 


/* determine whether this is an address or not */ 
if€ IsDigitC *curr_pos ) || *curr.pos == '.^ ) ( 


include «Strings.h»? val = ParseValue( ) ; 

*include <Math.h> )else( 

include <Ctype.h> if€ IsFunction( 2 2 ( 

Binclude «Stdio.h»? val = CallFunction( ) ; 
else ( 

Rinclude “MacCalc.h” val = ParseAddress( ) ; 

include "CalcData.h" 

"include "Parser.h"^ ) 

unsigned char *curr_pos = NULL ; SwitchC *curr.pos ) ( 

int parse_err = 0 ; case '^': 

Str255 buffer ; curr_postt+ ; 
val2 = ParseFactor( ) ; 

/* Simple algabraic expression parser */ val = powC val, val2 ) ; 
break ; 

double ParseFormulaC formula, error ) case '*'; 


unsigned char *formula ; 
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curr_pos++ ; 
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va12 = ParseFactor( ) ; ) 


val *= val2 ; сигг_роѕ++ ; 
break ; return column ; 
case '/': 
curr.pos** ; int IsFunction( ) 
val2 = ParseFactor( ) ; 
val /= val2 ; register unsigned char *p ; 
break ; 
) p = curr_pos ; 
else ( whileC IsAlphaC *p ) || IsDigit( *p ) ) ( 
curr.pos** ; ptt ; 
val = ParseExpression( ) ; ) 
ifC *curr.pos == ‘)’ ) ( return С *p == '(' 22 TRUE:FALSE ; 
curr.pos** ; ) 
Jelse ( double CallFunctionC 2 
parse_err = MISMATCHED_PARENTHESIS ; { 
unsigned char fun.name[32] ; 
) register unsigned char *p ; 
register int fun.number ; 
return С has_sign ? -( val 2:val ) ; register double value ; 


register ARG.PTR args ; 
double ParseValue( ) 


р = fun_name ; 


register double val = 0; whileC IsAlphaC *curr.pos ) || IsDigitC *curr.pos 2 2 ( 
хр = toupper( *curr_pos ) ; 
if€ IsDigit€ *curr_pos ) || € *curr.pos == '.^ 2 ) { p**; curr.pos**; 
val = atofC ) ; ) 
)else ( Xp = “AQ ; 
parse_err = INVALID_NUMBER ; curr.pos** ; 
args = BuildArg( ) ; 
return val ; 1С € funnumber = Lookup( fun_name ) ) > -1 ) ( 
) value = (*fun_table[fun_number].fun_ptr)( args ) ; 
double ParseAddress( ) )else( 


parse_err = INVALID_FUNCTION ; 
register int row ; 


register int column ; DestroyArgs( args ) ; 
register double val = 0 ; return value ; 
column = GetColumn( ) ; int LookupC fun_name ) 
row = GetRowC ) ; unsigned char *fun_name ; 
if€ С row > MAX_ROWS ) || С column > MAX_COLUMNS ) ) ( register int i = 0 ; 
рагѕе_егг = ADDRESS_TOO_LARGE ; 
else { whileC fun_tableli].fun_name(@] != 0 ) { 
val = curr_sheet_ptr-)sheet_datalrow- 1] [column- ifC !strcmp( fun_name, fun_tableli].fun_name ) ) ( 
1].value ; return i ; 
return val ; itt ; 
) 
int GetRowC ) return -1 ; 
register int row ; ARG_PTR BuildArg( ) 
( 
if€ IsDigitC *curr_pos 2 2 { int error ; 
row = *curr_pos - %”; ARG-PTR first_arg_ptr = NULL, last arg ptr = NULL, 
else { next_arg_ptr = NULL ; 


parse_err = INVALID_ADDRESS ; 
/* This needs to be changed so that recursive functions 


curr.pos** ; calls can be made */ 
whileC *curr.pos != ')^ ) ( 
return row ; next.arg ptr = GetArg( 2 ; 
next arg .ptr-?value = ParseExpression( ) ; 
int GetColumnC 2 next arg .ptr-?type = VALUE. ARC ; 
( if( *curr.pos == *,^ ) ( 
register int column ; сигг_роѕ++ ; 
if( IsAlphaC *curr_pos 2 2 ( if( last.arg.ptr != NULL ) ( 
ifC *curr_pos >= ‘a’ ) ( last_arg_ptr->next_arg = next.arg.ptr ; 
column = € *curr_pos - ‘a’ ) +1; 
Jelse ( ifC first_arg_ptr == NULL ) ( 
column = € *curr_pos - ‘A’ ) + 1; first_arg_ptr = next_arg_ptr ; 
else ( last_arg_ptr = next_arg_ptr ; 
parse_err = INVALID_ADDRESS ; ) 
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next_arg_ptr->next arg = NULL ; 


/* Now pass the last parenthesis by */ 
if€ *curr.pos == ‘)’ ) ( 
curr_postt ; 
return first arg.ptr ; 
Jelse { 
parse_err = MISMATCHED_PARENTHESIS ; 
return NULL ; 


) 
(ot atofC ) 


register double val = 0.0 ; 
register double val2 = 0.0; 


if€ IsDigitC *curr_pos ) || € *curr_pos == '.^ ) ) { 
whileC *curr_pos && IsDigitC *curr_pos 2 2 ( 
val = € val * 10 ) + (С *curr.pos - 40”); 
curr.pos** ; 


ifC *curr.pos == '.^ ) ( 
curr_post++ ; 


whileC *curr.pos && IsDigitC *curr_pos 2 2 ( 
val2 = ( val2 * 10 ) + ( *curr.pos - '0^ ) ; 
curr.pos** ; 


ifC val2 ! 0.0 2 ( 
whileC val2» 12 ( 
val2 /s 10; 


` 


val. += val2 ; 
Jelse ( 
parse_err = INVALID_NUMBER ; 


return val ; 


void ftoa( val, buffer ) 
double val ; 


unsi 
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gned char *buffer ; 


long whole ; 

Str255 buff ; 

Str255 tmp ; 

int has_sign ; 

int prec = /*curr.precision*/5 ; 


has-sign = ( val < 0 ) ? TRUE:FALSE ; 

whole = val/1 ; 

NumToStringC whole, buffer ) ; 

/* convert into c string in buffer */ 
BlockMoveC &buffer[11, buff, buffer(0] ) ; 
buff(buffer(01] = 0; /* 0 terminate buffer */ 
val -= whole ; 

if( prec ) ( 


val *= 10.0 ; 
)whileC -prec ) ; 
whole = val ; 
NumToStringC whole, buffer ) ; 
/* convert into c string in buffer */ 
BlockMoveC &buffer[1], tmp, buffer[0] 2; 
tmplbuffer(01] = 0 ; /* Ø terminate buffer */ 
strcetC buff, “.” ) ; 
strcat( buff, tmp ) ; 


if( has-sign ) ( 
tmp[0] = '-"' ; 
tmp[1] = ‘\8’ ; 
strcatC tmp, buff ) ; 
strcpyC &buffer[1], tmp ) ; 


buffer{@] = strlenC tmp ) ; 
)е1ѕе ( 

strcpyC &buffer(1], buff ) ; 

buffer(@] = strlenC buff ) ; 


return ; 


double GetFloat(€ formula, error ) 
unsigned char *formula ; 
int *error ; 


register double value ; 


/* convert into c string in buffer */ 
BlockMoveC &formula[1], buffer, formula[2] ) ; 
buffer[formula(01] = 0 ; /%0 terminate buffer */ 


curr_pos = buffer ; 
parse_err = 0; 
value = atof( ) ; 
*error = parse.err ; 
return ( value ) ; 


/* Set error flag */ 


) 
id GetArg( ) 
register int i ; 


forC 1=0;1‹30;1++)( 
if€ arg-free.pool[il.in.use == FREE. ARG 2 ( 
erg free pool[il.in.use = IN_USE ; 
return &arg free pool[i] ; 


) 
return NULL ; 


void DestroyArgs( arg.ptr ) 
ARG_PTR arg.ptr ; 


ifC arg_ptr != NULL 2 ( 
PutArg( arg_ptr ) ; 
whileC arg.ptr—next. arg != NULL 2 ( 
arg-ptr = arg .ptr- next arg ; 
PutArgC arg.ptr ) ; 


) 


return ; 


void PutArg( arg-ptr ) 
id arg-ptr ; 


arg-ptr-> in-use = FREE. ARG ; 
return ; 


Listing: SetType.c 


include «WindowMgr .h> 
include <ListMgr .h> 
®include «0SUtil.h» 
8include <EventMgr .h? 


include “MacCalc.h” 
include “CalcData.h” 
include “Рагѕег.ћ* 


void RemoveLeadingBlanks( unsigned char * ) ; 
void PackLineC unsigned char * ) ; 


void SetTypeC cell.ptr, had_data ) 
CELL_PTR cell.ptr ; 
int had.data ; 


ifC се11_ріг-› Рогти1а(0) != Ø 2 ( 
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RemoveLeadingBlanks( cell_ptr->formula ) ; 
ifC cell.ptr—formula[1] == ‘=’ ) ( /* formula */ 
cell.ptr-»type = FORMULA ; 
PackLineC cell_ptr->formula ) ; 
else ( 
if€ IsDigitC cell_ptr->formulali] ) || 
C cell.ptr—formulat1] == ’.’ 2 2 { 
cell.ptr-»type = CONSTANT ; 
Jelse ( 
cell_ptr->type = STRING ; 


)else ( 
if( had.data ) ( 
се11_ріг-› type = CLEARED ; 
)else ( 
се11_ріг-› type = UNDEFINED ; 


) 


return ; 


void RemoveLeadingBlanks( formula ) 
s char *formula ; 


int length ; 
unsigned char *str ; 


length = Ғогт/а(01; 

str = &formulalil] ; 

whileC С *str == ° * ) || C *str == "\t’ ) ) ( 
str++ ; 
length- ; 


BlockMoveC str, &formula[1], length ) ; 
formula[0] = length ; 
return ; 


) 
void PackLineC formula ) 
rid char *formula ; 


int old. length ; 

int new length ; 

int і; 

unsigned char *str ; 
Str255 buffer ; 

int str flag = FALSE ; 


old length = formula[£] ; 
пен length = 0; 
str = buffer ; 
for€ i21 ; i«» old length ; i++ 2 ( 
ifC С C formulali] != ° ° ) || strflag ) 
&& C formula[lil != ‘\t’ >) ( 
*str = formulalil ; 
ifC formulali] == *\** ) ( 
str flag = str_flag ? FALSE: TRUE ; 


new _length++ ; 
str++ ; 


) 
) 
BlockMove( buffer, &formula[1], new length ) ; 
formula[0] = new length ; 
return ; 
) 
Listing: SheetHndlg.c 


"include «ListMgr.h» 
Binclude «WindowMgr.h? 


*include “MacCalc.h” 
"include "SheetHndlg.h^ 
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char column header [MAX COLUMNS] = ( 
“А”, В”; 707; 0”, БУ К»; "675 ^H?) " 


char row-header [MAX_ROWS) = ('1^,72',/3', /4' ,/5' ,/6' "T ,'8') 


2 


void SetupRowandColumnHeader( ListHandle ) ; 
void InitData( SHEET_WIN_HDL ) ; 


int OpenNewSpreadsheet( title ) 
char *title ; 


WindowPtr new_window_ptr ; 
SHEET. WIN-.HDL new.sheet hdl ; 
Rect rView, dataBounds ; 
Point cSize ; 

int i ; 


/* variable initialization for screen */ 


new .window.ptr = GetNewWindow( 128, NULL, CWindowPtr )- IL 


); 
new_sheet_hd1 
=(SHEET_WIN_HDL )NewHandle(sizeof (SHEET_WIN)); 


/* Set the window title */ 
SetWTitle( new_window-ptr, title ) ; 


SetRect( &dataBounds, Ø, 0, MAX_COLUMNS+1, MAX_ROWS+1 ) ; 


SetRect( &rView, new_window_ptr->portRect. left, 
пен window ptr-»portRect top, 
new_window_ptr->portRect.right - 15, 


new. window. ptr-»portRect.bottom - 15 ) ; 


SetPt( &cSize, CELL WIDTH, CELL.HEIGTH ) ; 


(**new. sheet hdl).sheet list. hdl = LNewC &rView, &data- 


Bounds, cSize, 8,new window.ptr, TRUE, TRUE, TRUE, TRUE); 
SetWRefConC new.window.ptr, Clong)new_sheet_hdl ) ; 
InitDataC new.sheet.hdl ) ; 

(**new. sheet hdl2.sheet window.ptr = new window ptr ; 


(**(**new_sheet_hdl).sheet_list_hdl).1ClikLoop = 
(Ptr)ClikLoop ; 


SetupRowandColumnHeader C 
(**new_sheet_hdl).sheet_l1ist_hdl); 


ShowWindow( new_window-ptr ) ; 
return noErr ; 


void SetupRowandColumnHeader( list hdl ) 
eee list.hd! ; 


Cell curr_cell ; 

int i; 

i=; 

for( i = 1; i <= MAXROWS ; i** ) ( 


SetPt( &curr_cell, 1,0); 

LSetCellC &column_neader[i-1], 1, curr.cell, 
list.hd1); 

SetPtC &curr cell, 2, i); 

LSetCellC &row header[i-1], 1, curr-cell, list hdl 


return ; 


) 
void InitDataC sheet record.hdl ) 
зы sheet record hdl ; 
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int i,j ; 


for( i=0; i<MAX_ROWS; i++) ( 


for( j=0; j<MAX_COLUMNS; j++ ) ( 
(**sheet_record_hd1).sheet_datalil{j].type = 0 ; 


(**sheet_record_hdl).sheet_dataliJ(j).value = OL ; 
(**sheet_record_hd1).sheet_dataliJ(j].formula(@] = 


0; 
) 
) 


return ; 


Listing: Resources.r 
x 
* MacTutorCalc.R 


MacTutorCalc.rsrc 
222"? CAL x 


Type CALx = STR 
0 


Spreadsheet Demo \@D@ by Bryan 
Waters for MacTutor 


x Multif inder Menu for Quit Cmd 
Type mstr = STR 

, 100 
File 


* Multifinder Quit name 
Type mstr = STR 

, 101 
Quit 


Type SIZE = GNRL 
,-1 
.H 
0800 ;; $0800 = bits 11 set 
L 
80000 ;; ( recomended) 
L 


40000 ;; С minimum) 
I 


Type vers = GNRL 

.H 

01 ;; byte vers # in BCD 
10 ;; byte vers part 2 & 3 
50 3; byte release stage 
$50=re lease 

00 ;; bute stage of non- 
release 

00 00 ;; integer country 0-05 
P 


1.1 (US) 

P 

SpreadSheet Demo, @ by Bryan 
Waters for MacTutor 1989 


Type vers = GNRL 

.H 

05 ;; byte vers * in BCD 
30 ;; byte vers part 2 & 3 
50 ;; bute release stage 
$50-release 

00 ;; bute stage of non- 
release 

00 0@ ;; integer country 9=US 
iP 

V5.3 

P 
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x 


menus 


Type MENU 
,1 (0) 
\14 


Type MENU 

,256 (0) 
File 
Quit 


Type MENU 
,251 (0) 

Edit 

Undo 

(- 

Cut 

Copy 

Paste 

Clear 


Type WIND 

, 128 (0) 
MacCalc 
43 20 202 419 
Invisible GoAway 
0 
0 


Type DLOG 
, 128 (32) 
New Dialog 
208 70 330 424 
Visible NoGoAwau 
l 
0 
12258 


Tupe DITL 
, 12258 (0) 
4 


Button 
96 184 116 244 
Enter 


Button 
96 264 116 324 
Cancel 


staticText Disabled 
8 8 24 88 
Enter data: 


editText 
8 96 80 328 


Type DITL 
‚200 (0) 


3 


` Button 


56 160 76 220 
OK 


IconItem Disabled 
8 16 40 48 
128 


staticText Disabled 
24 56 40 224 


Mismatched Parenthesis. 


Type DITL 
,201 (0) 
3 


Button 
56 160 76 220 
OK 


IconItem Disabled 
8 16 40 48 
128 


staticText Disabled 
24 56 40 224 
Invalid Number. 


Type DITL 
,202 (0) 
3 


Button 
56 160 76 220 
OK 


IconItem Disabled 
8 16 49 48 
128 


staticText Disabled 
24 56 40 224 
Invalid address. 


Type DITL 
, 204 (0) 
3 


Button 
56 168 76 220 
OK 


IconItem Disabled 
8 16 40 48 
128 


staticlext Disabled 
24 56 40 224 
Invalid function. 


Type DITL 
‚203 (0) 


Button 
56 160 76 220 
OK 


IconItem Disabled 
8 16 40 48 
128 


staticText Disabled 
24 56 40 224 
Address too large. 


Type ALRT 

‚200 (32) 
118 94 214 338 
200 
4444 


Type ALRT 

‚201 (32) 
118 94 214 338 
201 
4444 


Type ALRT 

,202 (32) 
118 94 214 338 
202 
4444 


Tgpe ALRT 

,204 (32) 
118 94 214 338 
204 
4444 


Type ALRT 

‚293 (32) 
118 94 214 338 
203 
4444 


Tupe ICON = GNRL 

, 128 (32) 
.H 
0001 8000 0003 С000 0003 С000 
0006 6000 
0006 6000 000С 3000 000С 3000 
0018 1800 
00 19 9800 0033 СС00 0033 СС00 
0063 С600 
0063 C600 00С3 C300 00С3 C300 
0183 С180 
0183 C180 0303 COCO 0303 С0С0 
0603 С060 
0601 8060 0С01 8030 0С00 0030 
1800 0018 
1801 8018 3003 С00С 3003 С00С 
6001 8006 
6000 0006 (000 0003 FFFF FFFF 
ТЕҒЕ FFFE 


<—. 


sel 


ciun 
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C Workshop 
All About Scrolling Windows 


A Scrolling Manager 
Why and How to Scroll 

The Macintosh user interface is based on windows. Win- 
dowsprovide a solution to the problem of keeping track of much 
information on a single computer screen. Each window can be 
structured to contain a single document. By document,I mean a 
logically connected set of text, graphics, or text and graphics that 
provides the working environment for a particular application. 
By the process of activating a window which brings that window 
to the foreground, the user can work on the document in that 
window. While working in one window, the contents of deacti- 
vated windows are within easy reach - a mouse click away. 

Because the physical size of a window is limited to the 
physical size of the computer screen, а common occurrence will 
be that the document is larger than the window. In this situation, 
the window will only be able to display a portion of the document. 
The window based interface would fail if it were not possible to 
relocate the window and to display different portions of the 
document. The task of relocating windows or rather of reposi- 
tioning documents behind windows is accomplished by scroll 
bars. Two scroll bars are required - a vertical scroll bar for 
|» scrolling the window contents up or down and a horizontal scroll 
bar and for scrolling the window contents left or right. 

While scroll bars are an important user interface feature, like 
many other Macintosh features, their implementation is less than 
trivial. My first attemptat using scroll bars was a time consuming 
process. Aided by an excellent book (C Programming Tech- 
niques for the Macintosh™ by Z. R. Mednieks and T. M. Schilke) 
and after much trial and error, I was able to work out the kinks of 
window scrolling. My second attempt was much easier and 
remarkable similar to the first attempt. After a few more attempts, 
I decided it was time to generalize the scrolling routines to elevate 
inclusion of scrolling in applications to the trivial matter that it 
ought to be. 

My efforts aimed at generalizing window scrolling have 
been developed into a scrolling manager. Using the scrolling 
manager and relatively few lines of code any window can be 
converted into a scrolling window. The window can have both 
vertical and horizontal scroll bars. The contents of the window 
сап be graphic (i.e. application defined) or can contain a Text Edit 
record. Using the scrolling interface described in the next section, 
the scrolling manager supports tool bars and rulers. Additional 
features include automatic scrolling while selecting, drag scroll- 
ing, joy-stick scrolling, and automatic tracking of the selection 
point. This article will describe the development and use of the 
scrolling manager and illustrate its capabilities with a demonstra- 
tion application. 
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Figure 1. Scrollbars and Toolbars 


A Scrolling Interface 

The document windowin the figure illustrates the important 
objects for the scrolling interface supported by the scrolling 
manager. The objects include vertical and horizontal scroll bars, 
tool bars, and rulers. The functions and the placement of each of 
these objects will be discussed in this section. 

In virtually all applications, the horizontal scroll bar is along 
the bottom of the window with the right edge touching the size 
box in the lower right-hand corner of the window. Typically, the 
horizontal scroll bar extends the full width of the window with the 
left edge of the scroll bar touching the left edge of the window. 
Some applications stop the horizontal scroll bar before the left 
edge and leave a scroll bar margin which is used for some 
application-defined purpose (See figure). The scrolling interface 
defined by the scrolling manager supports horizontal scroll bars 
with one end touching the size box and the other end stopping an 
application-defined margin from the left edge of the window. 

Vertical scroll bars are universally along the right edge of the 
window. In analogy with horizontal scroll bars, the scrolling 
manager supports vertical scroll bars whose bottom touches the 
size box and whose top stops at an application-defined margin 
from the top of the window. 

The function of the scroll bars should be second nature to all 
experienced Macintosh users and will not be discussed at length 
here. In brief, the arrows scroll one line at a time, the gray regions 
between the arrows and the scroll box scroll one “page” (i.e. one 
window full) at a time and by dragging the scroll box, you can 
scroll to any position in the document. 

Some applications (e.g. MacDraw™ ) incorporate tool bars 
along the edge of their windows. The tool bar areas are static 
areas that do not scroll as the contents of the rest of the window 
scrolls. While the most common use of tool bars will be to 
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provide tools for the user, they can be used to display any static 
information that is meaningful to a particular application. 

The scrolling manager supports vertical and/or horizontal 
tool bars. The vertical tool bar is a static area of application- 
defined width along the left edge of the window extending from 
the top of the window to the top of the horizontal scroll bar. The 
horizontal tool bar of application-defined height is along the top 
of the window and extends from the left edge of the window to 
the left edge of the vertical scroll bar. 

Another common feature of in windows is rulers. Rulers are 
typically used in graphics applications to mark and measure 
position within a drawing. When scrolling occurs, the rulers 
should sometimes scroll and sometimes remain stationary. 
Consider for example a vertical ruler. As the window is scrolled 
in the vertical direction, the ruler should scroll along with the 
window contents. But, when horizontal scrolling occurs, the 
ruler should remain stationary otherwise it might scroll out of 
view. Likewise, horizontal rulers should scroll in the horizontal 
direction but remain stationary during vertical scrolling. 

The scrolling manager supports vertical and/or horizontal 
rulers. The vertical ruler is of application-defined width and is 
just to the right of the vertical tool bar. The horizontal ruler is of 
application-defined height and is just below the horizontal tool 
bar. 

The contents of rulers are not restricted to ruler markings. 
The ruler area, for example, might also include row and column 
labels in spreadsheet software. In terms of scrolling, row and 
column labels are logically equivalent to vertical and horizontal 
rulers. During vertical or row scrolling, row labels, just as vertical 
rulers, should scroll along with the window contents. During 
horizontal or column scrolling, the row labels, again just as 
vertical rulers, should remain stationary. 

The last scrolling object is the content region which is the 
area of the window left for the document after removing the areas 
occupied by the size box, the scroll bars, the tool bars, and the 
rulers. In any scrolling window, the content region will be 
rectangular. 

The scrolling objects defined in this section comprise a 
workable user-interface for scrolling windows. We note that the 
windows in virtually all Macintosh applications can be described 
by using some subset of these scrolling objects. The scrolling in 
all these applications could therefore be handled using the 
scrolling manager. 

Scrolling in some applications could not be handled with the 
scrolling manager because those applications select “unusual” 
locations for scrolling objects. In Adobe™ Illustrator, for ex- 
ample, the rulers appear adjacent to the scroll bars rather than 
adjacent to the tool bars. Rulers in the position I described, 
however, would be equally functional to rulers located else- 
where. I therefore see no compelling reason for choosing a 
variety of ruler locations in a variety of different applications. It 
can be argued instead, that the user should be provided with a 
consistent scrolling interface. By providing specific locations for 
scroll bars, tool bars, and rulers, the scrolling manager attempts 
to provide a consistent scrolling interface. 

The scrolling manager was developed to be stable with 
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respect to all subsets of scrolling objects. Although this stability 
includes subsets lacking one or even both scroll bars, I view the 
use of less then the full complement of scroll bars a violation 
(albeit a mild one) of the Macintosh user interface. When an 
application does not provide scroll bars, the user is limited in his 
options as to the size of the document window. If the window is 
made too small, the user will not be able to view the entire 
document without the inconvenience of resizing the window. In 
short the user’s desktop ceases to be efficiently customizable to 
fit all user’s needs. Before MultiFinder, limitations on window 
sizes were not very severe. But under MultiFinder, with the 
possibility of many open windows, the user may have valid 
reasons for resizing windows in ways not envisioned be develop- 
ers of specific applications. I therefore suggest that all document 
windows, no matter what their contents, should include both 
vertical and horizontal scroll bars. 


Scrollinfo Record 
To operate window scrolling, the scrolling manager needs to 
know which scroll bars to include, the size and whether or not to 
include tool bars and rulers, and some other information related 
to scrolling. This information is contained in a data structure of 
type ScrollInfo which is defined as follows: 


typedef struct ( 
ControlHandle hScrollHd!; 


int horizL ines; 

int horizLinesVis; 
Rect horizScrollRect; 
Point hRectTopLeft; 
int hScrollMarg; 
ControlHandle vScrollHdl; 
int vertLines; 

int vertLinesVis; 
Rect vertScrollRect; 
Point vRectTopLeft; 
int vScrollMerg; 
TEHendle hTE; 

long refCon; 


) ScrollInfo, *ScrollPtr; 


The hScrollHdl and vScrollHdl fields are handles for the 
scroll bars. Although as discussed in the introduction, it is 
recommended that all windows use both scroll bars, the scrolling 
manager will support windows with one or even with no scroll 
bars. When a scroll bar is absent, its handle field is set to NIL. 

The horizLines and vertLines fields specify the total 
number of lines in the document. This information is needed to 
set the range of the scroll bars. 

The horizLinesVis and vertLinesVis fields give the num- 
ber of lines currently visible in the window. When the window is 
resized, these fields are adjusted accordingly. 

The scrolling manager will also need to know the vertical 
and horizontal line size in number of pixels per line. This line size 
is used to calculate the number of lines in the document and the 
number of lines currently visible. The line size is also used to 
decide the number of pixels that should be scrolled when the user 
clicks in the scroll bar arrows and therefore calls for scrolling one 
line at a time. 

Ifthe linesizeistoo small, scrolling will besmooth but might 
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be too slow. If the line size is too large, scrolling will be fast but 
might be jerky. A happy medium can usually be found with line 
sizes between 8 and 16 pixels. For vertical scrolling of text 
windows, it make sense to set the vertical line size to the number 
of pixels in one line of text. 

The scrolling manager stores the vertical and horizontal line 
sizes in the refCon’s of the scroll bars. The horizontal line size is 
stored as minus the horizontal line size. With this scheme, by 
checking the sign of a scroll bar’s refCon, the scrolling manager 
can determine if a given control handle corresponds to a horizon- 
tal or to a vertical scroll bar. 

When the user initiates scrolling, the scrolling manager 
eventually calls the QuickDraw routine ScrollRect() which 
scrolls a specified rectangle by a specified number of pixels in the 
vertical or horizontal directions. The horizScrollRect and 
vertScrollRect fields are the rectangles passed to ScroliRect() 
during horizontal or vertical scrolling, respectively. The hor- 
izScrollRect will include the content region and the horizontal 
ruler. The vertScrollRect will include the content region and the 
vertical ruler. For windows which contain rulers, these two 
rectangles will be different. 

The hRectTopLeft and vRectTopLeft fields are used to 
define the scrolling rectangles and they give the top-left corner of 
the rectangles. The bottom-right corner of the scrolling rec- 
tangles will be at the top-left corner of the size box when both 
scroll bars are being used and will extend to the window edge 
when one of the scroll bars is missing. These fields also deter- 
mine the presence or absence and the size of tool bars and rulers. 

The vScrollMarg and hScrollMarg fields contain the scroll 
bar margins illustrated in the figure. 

For text windows that use the Text Edit manager, the field 
hTE holds the handle to the Text Edit record. 

Finally, the refCon field is provided for application-defined 
contents. A logical use of the refCon and the reason for its 
inclusion are described latter. 


Using The Scrolling Manager 

Typical event-driven applications have sections of code that 
handle common events such as activating, deactivating, and 
updating windows or responding to key down or mouse events. 
Within these or other common sections of code, simple calls to 
the scrolling manager will take care of all scrolling. 

When a new scrolling window is created, call Set- 
ScrollWindow() which will return a pointer to the ScrollInfo 
record. This pointer will need to be passed to many of the 
scrolling manager routines. 

The procedures ScrollActivate() and ScrollDeactivate() 
must be called whenever an activate or a deactivate event is 
reported for a scrolling window. These routines take care of 
hilighting or unhilighting the scroll bars and also set an internal 
ScrollInfo record pointer which points to the current active 
window's ScrollInfo record. The internal pointer is used by 
routines which apply only to the currently active window. 

Whenever an active window is resized call GrowScroll() 
which moves and resizes the scroll bars. Before and immediately 
after resizing the window using SizeWindow(), call InvalBars() 
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which invalidates the scroll bar rectangles to insure that the old 
scroll bars are erased and that the new scroll bars are correctly 
drawn. 

The section of code which updates window contents must be 
written to be accessible by a call using 


UpdateWindowCupWind, scrollType) 


where upWind is a pointer to the window requiring updat- 
ing and scrollT ype will be equal to VertBar (1) or HorizBar (2) 
when called from the scrolling manager and should be FALSE 
(0) when called from your application. The way applications 
should use scrollT ype is discussed latter. 

Whenever the document changes size in either the vertical or 
horizontal directions, call SetScroll(). This routine will reset the 
appropriate variable vertLines or horizLines and will reset the 
appropriate scroll bar's maximum value. 

When a mouse down event in the content of a window is 
reported call DoScroll(). If DoScroll() retums FALSE then 
handle the mouse down event as appropriate. If DoScroll() 
returns TRUE then the mouse down event was a scrolling event 
that was handled by the scrolling manager and no further action 
needs to be taken. 

Whenthe user is makinga selection of text or of graphics and 
drags the mouse outside the window, it is desirable to implement 
autoscrolling to enable the user to make a selection that is larger 
than the window. Implementing autoscrolling in Text Edit win- 
dows is easy - merely replace the standard call to TEClick() with 
a call to ScrolITEClick(). ScrolITEClick() calls TEClick() 
from a section of code that will always be in the same code 
segment as the click loop routine provided by the scrolling 
manager. 

Implementing autoscrolling in graphic windows is not much 
harder. Whenever the application believes that autoscrolling 
may be necessary, a call to FollowMouse() will scroll the 
window in the direction of the mouse if the mouse has been 
dragged out of the content region. An example of graphic 
autoscrolling while drawing a polygon is given in the routine 
TrackPoly() in the listing of Scroller. 

A second need for autoscrolling arises when the current 
selection is not visible in the window and the user performs some 
operation on it. Inside Macintosh recommends that applications 
scroll the selection into view before performing the operation. 
The two routines FixInsertPt() and FixTEInsertPt() scroll the 
insertion point of the active window into view. The latter brings 
the insertion point in Text Edit windows into view. If no place 
else, FixTEInsertPt() should be called after every key down 
eventin Text Edit windows. This call will insure that the window 
scrolls as the user types beyond the bottom of the window. 

It might be desirable to provide the user with alternative 
means to scrolling. Two such means in the scrolling manager are 
drag scrolling and joy-stick scrolling. Drag scrolling is available 
in many applications as a hand tool. As the mouse is clicked and 
dragged using the hand tool, the window is dragged along with 
it. Using the scrolling manager, when a mouse down event is 
reported and drag scrolling should follow, call DragScroll(). 
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Injoy-stick scrolling, the mouse is clicked at some point and 
dragged in any direction. The window is scrolled in the direction 
that the mouse is dragged and is scrolled faster the farther the 
mouse is dragged from the original point. Using the scrolling 
manager, when a mouse down event is reported and joy-stick 
scrolling should follow, call JoyStickScroll(). The joy-stick 
sensitivity, or how far the mouse must be dragged from the initial 
point to increase scrolling speed, is set by calling SetJoySpeed(). 

When a scrolling window is closed and the ScrollInfo 
record was allocated in the heap, call DisposeScroll(). 

A number of routines in the scrolling manager are provided 
as useful utilities: 

GetMargins(): returns distance of the top-left corner of the 
window to the top-left corner of the document in pixels or in 
scrolling lines. This routine should probably be called from your 
update routine to determine which part of the document should 
be drawn. 

ScrollSectRect(): returns a pointer to a rectangle which is 
the intersection of the vertScrollRect and the horizScrollRect 
and will usually define the content region. 

ScrollSectRgn(): same as ScrollSectRect() except returns 
a handle to a region. If the window has no scroll bars, the region 
will also exclude the size box. 

NonScrollRect(): returns pointer to rectangle that excludes 
the window 's scroll bars. 

ScrollDrawGrowlcon(): replaces Toolbox 
DrawGrowlIcon() and only draws the parts of the grow icon 
needed to outline the window's scroll bars. 

GetSRefCon(): returns the refCon in the ScrollInfo record. 

SetSRefCon(): sets the refCon in the ScrollInfo record. 

ActiveScrollPtr(): returns the ScrollPtr to the current ac- 
tive scrolling window. 

Any routines in the scrolling manager not discussed in this 
section are intended for internal use. 

AS a bottom line, the scrolling manager does not require 
much work to implement. The most optimal situation would be 
a document that never changes size. Scrolling in this window 
would only take 7 lines of code. These lines would be calls to 
SetScrolIWindow(), ScrollActivate(), ScrollDeactivate(), 
GrowScroll(), DoScroll(), and two calls to InvalBars(). Adding 
additional scrolling features such as variable size documents, 
autoscrolling, drag scrolling, and joy-stick scrolling will only 
require a few more lines of code. 


Sample Application: Scroller 

The source code for the application Scroller follows this 
article. The first half of the listing is the header and the source 
code for the scrolling manager. The second half is the source code 
for Scroller which functions to demonstrate the features of the 
scrolling manager. 

Scroller hasonly two menus - File and Edit menus. Under the 
File menu are the various settings for the features in the scrolling 
window (see figure). The window can be a Text Edit window or 
a graphics window. The window can have tool bars and/or rulers. 
The window can have both scroll bars, only one scroll bar, or no 
scroll bars. Selecting one of the File menu items will check that 
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menu item and incorporate that scrolling feature into the next 
scrolling window. 

Once the desired scrolling features are checked, choose 
"New Window" and a scrolling window incorporating those 
features will be created. Only one window will ever be present in 
Scroller. If "New Window" is selected and a window is currently 
open, that current window will first be closed. Note also, that 
selecting scrolling features in the File menu will only take effect 
on the next window and will not effect the current window if one 
is open. 

Graphic windows will open with a blank drawing that is ten 
inches square. For demonstration purposes, the mouse will 
function as a polygon tool. On each click and drag, a line segment 
will be drawn from the previous polygon point to the current 
mouse location. If you click and drag outside the content region, 
the window will autoscroll until it reaches the edge of the 
drawing. 

Text windows will open with a paragraph of text. You can 
type into this window and cut and paste text using standard 
Macintosh text handling procedures. The Edit menu , which has 
the standard editing commands, will be enabled for Text Edit 
windows. 

One feature not accessible in the File menu are the scroll-bar 
margins. To illustrate use of scroll-bar margins, Scroller will set 
the margins to the width of the tool bars whenever tool bars are 
present. In actually use, it is of course possible to set the scroll- 
bar margins to any value independent of the width of the tool bars. 

Finally, drag scrolling and joy-stick scrolling can also be 
tried using Scroller. To scroll using drag scrolling hold down the 
option key. To scroll using joy-stick scrolling hold down the shift 
and the option keys. For drag scrolling the cursor changes to the 
standard hand shape. For joy-stick scrolling, the cursor changes 
to four small arrows pointing up, down, left, and right. 


Technical Comments 

The most important sections of the scrolling manager are the 
routines that actually do the scrolling. All scrolling, whether 
scroll-bar scrolling, drag scrolling, joy-stick scrolling, or au- 
toscrolling is eventually handled by the internal routine 
ScrollWindow(theWindow, units) which scrolls the window 
pointed to by theWindow by units lines. Before calling 
ScrollWindow() the variables scrip (a pointer to the active 
window's ScrollInfo record) and scrollType (equal to VertBar 
(1) or HorizBar (2)) will have already been set. The way these 
variable get set will depend on the type of scrolling occurring. 

In brief, ScrollWindow( will call ScrollRect() for graphics 
windows and call TEScroll() for Text Edit windows. If a Text 
Edit window has rulers than a call to ScrollRect() will be 
required to scroll the contents of the rulers. For purely Text Edit 
windows, the call to TEScroll() completes the job. Apparently 
TEScroll() calls TEUpdate() and therefore automatically up- 
dates the text. Graphics windows or Text Edit windows with 
rulers will have some application-defined contents. To update 
the application-defined portions of these windows that may have 
been disturbed by scrolling, ScrollWindow() ends by calling 
UpdateWindow() which as discussed above must be supplied by 
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the application. Note that the application supplied Update Win- 
dow()routine must check the current scroll bar margins to draw 
the correct part of the document. The routine GetMargins() is 
provided to simplify this task. 

The scrolling speed is determined by a combination of 
number of pixels per line and the efficiency of the scrolling 
manager routines. For a given line size, it turns out that the 
limiting factor in scrolling speed is the speed at which the 
application supplied routine UpdateWindow() can update the 
window contents. The variable scrollType is supplied to Up- 
dateWindow() to help in updating efficiency. When Up- 
dateWindow() is called from ScrollWindow(), scrollT ype will 
be equal to VertBar (1) or HorizBar (2) at which time only the 
contents of the vertScrollRect or of the horizScrollRect respec- 
tively will need to be redrawn. When UpdateWindow() is called 
from the application scrollType should be FALSE (0) and the 
whole window may need to be redrawn. 

Because the efficiency of UpdateWindow() is crucial, 
applications that use rulers should use clever means of quickly 
drawing them. The application Scroller does not usea clever ruler 
scheme and the slow down in scrolling between windows with 
and without rulers is apparent. The techniques used for updating 
the tool bars are not important because they need never be called 
while scrolling. 

With Inside Macintosh Volume IV autoscrolling was imple- 
mented into the Text Edit routines. Because the Text Edit 
autoscrolling routines are not aware of the details of the 
window's scrolling interface, they were not of use in developing 
the scrolling manager. For Text Edit windows which haverulers, 
the scrolling manager will have to handle autoscrolling of the 
rulers anyway, so it might as well do the text autoscrolling at the 
same time. 

To handle autoscrolling while selecting, the scrolling man- 
ager provides a default click loop called SMClikLoopO. The 
click loop routine merely checks the mouse location and scrolls 
one line in the appropriate direction if it is outside the Text Edit 
view rectangle. One complicating aspect of developing the click 
loop is that TEClick() which calls the click loop apparently sets 
the clip region to the view rectangle. The click loop routine must 
reset the clip region to the entire window otherwise the scroll bar 
graphics and the rulers will not scroll appropriately during 
autoscrolling. The click loop routine also better restore the clip 
region before returning to TEClick() or else the inverting of the 
selected text will not occur correctly. I would have been saved 
several hours of work had Inside Macintosh included a warning 
regarding the clip region and TEClick(). 

The hardest part of Text Edit autoscrolling was the routine 
FixTEInsertPt() which scrolls the beginning of the selection 
region into view. This routine is typically called whenever 
TEKey(), TECut(), TEDelete(), or TEPaste() have been called. 
Calls to FixTEInsertPt() will become frequent while the user is 
typing in text and it therefore must be fast. 

FixTEInsertPt() begins with a binary search through the 
lineStarts array in the Text Edit record to find the line which has 
the start of the current selection. The search begins at the last line. 
By starting on the last line Fix TEInsertPt() will be fastest during 
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the most common form of typing which is adding new text at the 
end of document. Even for large Text Edit documents (which are 
limited to 32K) a binary search to any location in the document 
is fast. Frequent calls to FixTEInsertPt() will therefore not 
result in any response problems while entering text. 

I like to think part of the speed of FixTEInsertPt() was a 
result of careful attention to the code for the binary search. 
Experienced C programmers could certainly see ways of short- 
ening the code and making it look more elegant. My goal, 
however, was not to create concise C code but to optimize the 
machine code generated by LightSpeed C™. To achieve this 
goal, I used MacBugs to examine the machine code generated for 
the binary search. The C code was then modified until I ended up 
with the result given in the attached source code. The final 
machine code had about half the number of lines per loop and 
therefore is probably about twice as fast as the machine code 
resulting from more concise C code. Some of the key changes 
were to set up pointers before entering the search loop, use 
register variables wherever possible, and use logical operations 
(e.g. shifts) instead of arithmetic expressions wherever possible. 

Inote that FixTEInsertPt() assumes constant line heights as 
was always the case for original Text Edit records. With the 
recent implementation of various text attributes within a single 
Text Edit record, FixTEInsertPt() will have to be modified. The 
changes will be relatively minor and I plan to get to it as soon as 
I need that feature (or maybe even sooner). 

In multiwindow applications, the application usually will 
not be concerned with what window is scrolling. Many of the 
scrolling interface sections of code can therefore be generalized 
to handle any window. One thing the application will probably 
need to know will be the pointer to the ScrollInfo record for each 
window. This pointer can be stored in the windows refCon and 
therefore always be available. For this strategy not to cause the 
loss of other uses for the window's refCon, a replacement 
refCon is provided in the ScrollInfo record. 


Scrolling Manager Routines 
The useful routines in the scrolling manger are described in 
the section "Using the Scrolling Manager." The calling proce- 
dures; that is, the type and description of the required parameters 
for each routine, are contained in the comments in the source 


code. 
Listing: ScroliMgr.h 


/*Header file for scrolling manager 
€ 1988 John A. Nairn, All Rights Reserved */ 


Bifndef ControlMgr. 
8include «ControlMgr.h? 
"endif 

"ifndef _TextEdit_ 
Sinclude «TextEdit.h» 
епа? 


ifndef _МасТуреѕ_ 
8include ‹МасТуреѕ.ћ› 
епаіѓ 


#def ine SBarWidth 15/*Standard Constants*/ 
“define HorizBar 1 
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tdefine VertBar 2 not include scroll bar) 


"define inPixels 0 4. v or hTotalLines: number of lines in document 
define inLines 1 5. v or hTools: width of tool bars in pixels (Ø if 
no tool bar) 
typedef struct ( 6. v or hRuler: width of rulers in pixels (Ø if no 
ControlHandle hScrollHd!; ruler) 
int horizLines; T. vScrollTop or hScrollLeft: scroll bar margins 
int horizLinesVis; 8. sRefCon: ScrollInfo refCon */ 


Rect horizScrollRect; 
Point hRectTopLeft; 
int hScrollMarg; 
ControlHandle vScrollHdl; 
int vertL ines; 
int vertLinesVis; 
Rect vertScrollRect; 
Point vRectTopLeft; 
int vScrollMarg; 
TEHandle hTE; 
long refCon; 

) ScrollInfo, *Scrol1Ptr; 


ScrollPtr SetScrollWindowC2; 
RgnHandle ScrollSectRgn(C); 
Rect *NonScrollRect(); 

Rect *ScrollSectRect C); 

long GetSRefCon(); 

ScrollPtr ActiveScrol1Ptr(); 


Listing: Scroll.c 


/* Scrolling Manager Library of Subroutines 
€ 1988 John A. Nairn, A11 Rights Reserved 


This library of routines allow any application to 
easily inplement scrolling in any window. The library 


cen hendle application-def ined graphic windows as well 


as Text Edit windows. 


General variables appearing as common parameters 
1. theScrip: the ScrollPtr for scrolling window 
2. theWindow: window pointer to scrolling window 


Routines marked “internal use? should not need to be 
called by the application 


WARNING: A number of these routines assume scrolling 
is occurring in the active window. This means 
that ScrollActivateC) must have been called 
before calling these routines. Failure to do so 
may result in system crash. 

жу 

*include «MacTypes.h? /* Includes */ 
*Sinclude «QuickDrew.h» 
"include «ControlMgr.h? 
*include «TextEdit.h? 
include "ScrollMgr.h" 
"def ine Active 0 
define Inactive 255 
def ine NIL ØL 


/* defines */ 


ScrollPtr scrip; /* Global Variables */ 

int scrollAmt,scrollCode,scrollType, linesVis, lineS ize; 
int vJoySpeed=8 ; hJoySpeed=8 ; 

pascal Boolean SMClikLoop(); 


/* Initialize ScollInfo data record for new window and 
return ScrollPtr as the function return. Note 
this routine calls ScrollActivate() to activate 
the scroll bars. 

1. theScrlp: pointer to use for ScrollInfo or NIL to 
put Scrollinfo in heap 

2. textWindow=TRUE if Text Edit window else =FALSE 

3. у or hLineSize: pixels per line to scroll (0 to 
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vLineSize, vTotalL ines, vTools, vRuler, 


vScrollTop,hL ineSize,hTotalL ines,hTools, 


hRuler,hScrollLef t, sRef Con) 
WindowPtr theWindow; 
ScrollPtr theScr]p; 
Boolean textWindow; 
int vLineSize,vTotalL ines, vTools, vRuler; 
int vScrollTop,hL ineSize,hTotalL ines, hTools; 
int hRuler,hScrollLeft; 
long sRefCon; 


ScrollPtr newscrlp; 
Rect viewRect,scrollRect; 


if (theScr 1p==NIL) 
newscr lp=(Scrollinfo *) 
NewPtr( (Size sizeof (ScrollInfo)); 
else 
newscr lpstheScr lp; 


/*vertical scoll bar initialization*/ 
newscr1p-? vScrollMarg-vScrol1Top; 
newscr1p-? vRectTopLef t . vehTools*hRuler; 
newscr1p-? vRectTopLef t .h-vTools; 
if CvLineSize!z0) 
( SetVertRect(newscr Ip, theWindow, vLineSize, 
hLineSize); 
scrollRect-theWindow-?portRect; 
scrollRect.left-scrollRect.right-SBarWidth; 
scrollRect.right**1; 
scrollRect .bottom-2 14; 
scrollRect . {ор-= 1-newscrlp-?vScrollMarg; 
newscrp-? vScrollHdlsNewControlCtheWindow, 
&scrollRect, “Ар”, 1,0,0,0, scrollBarProc, 
Clong)vLineSize); 
) SetScrollCnewscrlp, vTotalL ines, VertBar); 
else 
newscr 1p-? vScrollHdlsNIL; 


/*horizontal scoll bar initialization */ 
newscr lp-?hScrollMarg-hScrollLeft; 
newscrlp-^hRectTopLef t . vshTools; 
newscr 1p-»hRectTopLef t .hzvTools*vRuler; 
if ChLineSize!=8) 
( SetHorizRect(newscr Ip, theWindow,hL ineS ize, 
vLineSize); 
scrollRectstheWindow-?portRect; 
scrollRect.left-21-newscrlp-?hScrollMarg; 
scrollRect.right-2SBarWidth- 1; 
scrollRect.top-scrollRect .bot tom-SBarWidth; 
scrollRect.bottom+=1; 
newscrlp-»hScrollHdlsNewControl(CtheWindow, 
&scrollRect, "p^, 1,0,0,0, scrollBarProc, 
Clong)(-hLineSize)); 
SetScroll(newscrlp,hTotalL ines, Hor izBar ); 
else 
newscr 1p-»hScrollHdlsNIL; 


/*Text edit initialization Cif text window) 


if CtextWindow) 


( ScrollSectRect(newser Ip, theWindow, &viewRect); 
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ScrollPtr SetScrollWindowCtheWindow, theScrip, textWindow, 


*/ 


) 


newscrlp-? hTESTENewC&viewRect,&viewRect); 
SetClikLoopC&SMC1 ikLoop,newscrlp-?hTE); 


else 
newScrlp-^hTE-NIL; 


newscr 1p-?ref Con-sRef Con; 
ScrollActivateCnewscr 1p); 
return(Cnewscr Ip); 


/*Set the scrolling rectangles - internal use */ 


SetVer tRect(newscr 1p, theWindow, theL ineSize, hasHor izBar ) 


) 


ScrollPtr newscrlp; 
WindowPtr theWindow; 
int theLineSize,hasHor izBar; 


Rect r; 


r=theWindow->portRect; 
r.left*znewscrlp- vRectTopLef t .h; 
r.top*-newscrlp-?vRectTopLef t . v; 
r.cight-=SBarWidth; 
if ChasHor izBar ) 
r.bottom-=SBarWidth; 
newscrlp-?vertScrollRectsr; 
newscr lp->ver tLinesVis=(r.bottom-r. top)/theLineSize; 


SetHor izRectCnewscr 1р, theWindow, theL ineSize, hasVer tBar ) 


) 


ScrollPtr пежѕсг1р; 
WindowPtr theWindow; 
int theLineSize,hasVer tBar ; 


Rect r; 


r=theWindow->portRect; 
r.left*-newscrlp-^?hRectTopLeft.h; 
r.topt-newscrlp— hRectTopLeft.v; 
r.bottom--SBarWidth; 
if ChasVer tBar ) 
r.right--SBarWidth; 
newscrlp-?horizScrollRectsr; 
newscr Ip->horizLinesVis=(r .right-r. left)/theL ineSize; 


/*Call when window activates: will activate scroll bars 


and set internal pointer scrip to newscrlp which 
is ScrollPtr for window being activated */ 


ScrollActivate(newscrlp) 


ScrollPtr newscrlp; 


scr 1p=newscr Ip; 

if (scrlp->vScrollHd]!=NIL) 
HiliteControl(scr1p-»vScrol 1Hd1, Active); 

if (scr 1p->hScrollHd1!=NIL) 
HiliteControlCscrlp-^hScrollHdl,Active?); 


/*Call when window deactivates: will deactivate scroll 


bars. oldscrip is ScrollPtr for deactivating 
window */ 


ScrollDeactivateColdscrlp) 


ScrollPtr о19ѕсг1р; 


if Coldscrlp-?vScrollHdl!sNIL) 
HiliteControlColdscrilp-»vScrollHdl, Inactive); 

if Coldscrlp-»hScrollHdl!sNIL) 
HiliteControlColdscrlp-^»hScrollHdl, Inactive); 
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/*Call when scrolling window changes size. 
Note: assumes growing window is active window */ 


GrowScrollCtheWindow) 
WindowPtr theWindow; 


int theLineSize, hasOtherBar ; 
int newTop,newRight,newBottom,newLef t; 
Rect tempRect; 


if Cscrl1p-?vScrollHdl!sNIL) 
( /*Move vertical Bar */ 
newTop=theW indow->por tRect. top- 1+ 
scr 1p-?vScrollMarg; 
newRight=theW indow-> por tRect .right-SBarWidth; 
newBottom-theWindow-?portRect .bottom-SBarWidth; 
MoveControl(scrip->vScrollHd1,newRight,newlop); 
SizeControl(scrlp-?vScrollHdl, SBarWidth+ 1, 
newBottom-newTop* 1); 


/*Reset vertical scrolling rectangle */ 

theL ineSizezGetCRef ConCscr 1p-? vScrol1Hd12; 

has0 therBar=(scr 1p->hScro11Hdl !=NIL )?TRUE :FALSE; 

SetVertRect(scr lp, theWindow, thel ineSize, 
hasOtherBar); 


/*Reset vertical scroll bar range */ 
SetScrollCscrlp,scrlp-?vertL ines, Ver tBar ); 


) 


if (scr 1p-»hScro11Hd1!=NIL) 

( /*Move horizontal Bar */ 
newTop=theW indow-> por tRect .bottom-SBarWidth; 
newLef t=theWindow->portRect. lef t-1+ 

scr1p->hScrol iMarg; 
newRight-theWindow- por tRect .r ight-SBarWidth; 
MoveControl(scrlp-?hScrollHdl,newLef t, newTop?; 
SizeControl(scrlp-»hScrollHdl,newRight-newLef t* 1, 
SBarWidth* 1); 


/*Reset vertical scrolling rectangle */ 
theL ineSizez-GetCRef ConCscr1p-? hScrol1Hd1); 
hasOtherBarz(scr1p-? vScrol IHd] !=NIL J? TRUE :FALSE; 
SetHor izRect(scr 1р, theWindow, theLineSize, 

hasO therBar ); 


/*Reset vertical scroll bar range */ 
SetScrol1(scrlp,scr1p->horizLines, Hor izBar); 


) 


/*Reset view rectangle (if text window) */ 

if(scrlp-bhTE!=NIL) 

( ScrollSectRect(scrl1p,theWindow,&tempRect); 
(**scrlp-»hTED.viewRectztempRect ; 


) 


/*Invalidate the scroll bar area before and after 
window resizing */ 


InvalBarsCtheWindow) 
WindowPtr theWindow; 


Rect r; 


r=theWindow->portRect; /*Horizontal ScrollBar*/ 
r.top=r .bottom-SBarWidth; 

InvalRect(C&r ); 

r.top=theWindow->portRect.top; /*Vertical Scroll Bar*/ 
r.left=r .right-SBarWidth; 

InvalRectC&r ); 
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/*Reset a scroll bar range when the document changes 
size. Updates window if necessaru. 
1. totalLines: total Lines in document 
2. barTupe: VertBar or HorizBar*/ 


SetScrollCtheScrlp, totalL ines, barTgpe) 
ScrollPtr theScr ip; 
int totalLines, barType; 


int n,max,currentValue,numL inesVis, tempLineSize, units; 
WindowPtr ctr iWindow; 
ControlHandle scrol1Hd1; 


if Cbar Type==Ver {Ваг ) 

( tempLineSize=GetCRefCon(theScr 1p-» vScrollHd1); 
numL inesVisstheScr1p-? vertL inesVis; 
scrollHdlstheScr]1p-? vScro11Hd1; 
theScr 1p-? егі inesstotalL ines; 


else 

( tempLineSizez-GetCRef ConCtheScr 1p-?hScrollHdl); 
numL inesV is=theScr1p->horizLinesVis; 
scrollHdlstheScrlp-»hScrollHdl; 
theScrlp-?horizLines-totalLines; 


n-totalLines-numL inesVis; 
currentValue-GetCtValueCscrollHd1); 
пах=(п›0 ? n : Ø); 
SetCtlMax(scrollHdl1,max); 


/* if necessaru, scroll and redraw the window x/ 
if CcurrentValue> пах) 
( ctr 1Window=(*scro11Hd1 )-› contr 10wner ; 

InvalRect(&ctr1Window-> por tRect); 

if CtheScr 1p->»hTE!=NIL) 

( units=tempL ineSize*(currentValue-max); 

if Cbar Type==Ver tBar ) 
Of fsetRect(&(**theScr 1p-»hTE).destRect, 


Q units); 
else 
OffsetRect(&C**theScr 1p hTE)?.destRect, 
units,0); 


) 
) 
) 


/*Return current margins in pixels or in scrolling 
lines for window. 
1. left or topMargin: margin returned in 
these variables 
2. Im or tmType: set to inPixels C0) or 
inLines (1) for result in pixels 
or lines */ 


GetMarginsCtheScr p, lef tMargin, ImType, topMargin, tmType) 
ScrollPtr theScr]p; 
int *leftMargin, *topMargin, ImType, tmType; 


int theLineSize; 


if CtheScr1p-»?vScrollHdl!zNIL) 
( *topMargin=GetCt1Value( theScr 1p-?vScrollHdl); 
if CtmTypezzinPixels) 
( theLineSizesGetCRef ConCtheScr 1p-?vScro11Hd1); 
*topMargin*=theL ineS ize; 


) 

else 
xtopMargin=0; 

if(theScrlp->hScrollHd]!=NIL) 

( *leftMarginzGetCtlValueCtheScr1p-?hScro11Hd1); 
if ClmType==inPixels) 
( theLineSizez-GetCRef ConCtheScr 1p-»hScrol1Hd1); 
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*lef tMargin*=theLineSize; 


) 
else 
*lef tMargin=0; 


/*Find intersection of two scrolling rectangles, if no 
scroll bars, this rect will include the grow box 
1. drawRect: pointer to resulting rectangle - this 
pointer also returned as function value x/ 


Rect *ScrollSectRectCtheScr 1p, theWindow, drawRect) 
ScrollPtr theScr]p; 

WindowPtr theWindow; 

Rect *drawRect; 
NonScrollRectCtheScr p, theWindow, drawRect); 
drawRect-> top=theScr 1p-»vRectTopLef t.v; 
if CtheScr 1p->hRectTopLeft.v>drawRect-> top) 

drawRect-?topstheScrlp-»hRectTopLef t . v; 
drawRect-? lef t=theScr 1p-> vRectTopLef t .h; 
if CtheScr1p-»hRectTopLef t .h» drawRect-? left) 
drewRect-? lef t=theScr 1p hRectTopLef t .h; 
return(drawRect); 


) 


/*Return handle for region that is intersection of two 
scrolling rectangles. If no scroll bars, region will 
exclude grow box */ 


RgnHandle ScrollSectRgnCtheScr 1p, theWindow) 
ScrollPtr theScr 1p; 
WindowPtr theWindow; 


Rect r; 
RgnHandle drawRgn, tempRgn; 


ScrollSectRectCtheScr 1p, theWindow,&r 2; 

drawRgnzNewRgn(); 

RectRgnCdrawRgn, &г); 

if CCtheScr 1p vScrollHdl-2-NIL2&& 

CtheScr 1p-?»hScrollHdl2zNIL 2) 

( tempRgn-NewRgnO; 
r.leftstheWindow- portRect .right-SBarWidth; 
r. top=theWindow-> por tRect .bottom-SBarWidth; 
r.right=thewWindow->portRect .right; 
r.bottom=theW indow-> por tRect.bottom; 
RectRgnCtempRgn, &r); 
DiffRgnCdrawRgn, tempRgn, drawRgn); 
DisposeRgn( tempRgn); 


return(drawRgn); 


/*Calculate rectangle that excludes the scroll bars 
1. drawRect: pointer to resulting rectangle - this 
pointer also returned as function value */ 


Rect *NonScrollRect(theScr 1p, theWindow, drawRect) 
ScrollPtr theScrlp; 
WindowPtr theWindow; 
Rect *drawRect; 


*drawRect=theWindow->portRect; 
if CtheScr1p-? vScrollHdl!sNIL) 
drawRect-»right-2SBarWidth; 
if CtheScr1p-»hScrollHdl!sNIL) 
drawRect-»bottom--SBarWidth; 
returnCdrawRect); 


) 


/*Draw enough grow icon to enclose active scroll bars */ 


@ The Best of MacTutor, Vol. 5 


ScrollDrawGrowIcon(CtheScrlp, theWindow) 


) 


ScrollPtr theScrlp; 
WindowPtr theWindow; 


Rect r; 
RgnHandle tempRgn; 


GetClipCtempRgnzNewRgn(C)); 

rztheWindow-?portRect; 

if CtheScr1p-? vScro] 1Hd1==NIL) 
r.top=r .bottom-SBarWidth; 

if CtheScr 1p->hScrol1Hd1==NIL ) 
r.left=r.right-SBarWidth; 

ClipRectC&r); 

DrawGrowIconCtheWindow); 

SetClipCtempRgn); 

DisposeRgn( tempRgn); 


/*Action procedure for scrolling - internal use 


Scroll by scrollAmt (set by до5сго11) 

ScrollCode is the part of the scroll bar being tracked 

(set by doScroll) ScrollType is type of scroll bar 

(set by doScrol1) 

May also be called for tracking selections. In this 
case scrollType will be set by setSelectScrol1, 
scrollAmt will be 1 or -1 (set by ѕе1есі$сго11) 
and scrollCode will be set to 0. */ 


pascal void ScrollProcCcontrol, theCode) 


) 


ControlHandle control; 
int theCode; 


int max,oldValue,newValue; 
WindowPtr ctrlWindowsC*control)-?contr Owner; 


if CtheCodez-scrollCode) 

( oldValue-zGetCtlValueCcontro1); 
newValue-oldValue*scrollAmt; 
if (newValue<@) newValue=0; 
nax-GetCtMaxCcontro1); 
if (newValue>max) newValue-max; 
SetCtlValueCcontrol,newValue); 
ThumbMoveCctr 1Window, oldValue, newValue); 


) 


/*Do scrolling, return TRUE if scrolled or FALSE if not 


1. where: mouse location in Global coordinates 
Note: assumes scrolling in current active window */ 


DoScrollCtheWindow, where) 


WindowPtr theWindow; 
long where; 


int partCode,oldValue,newValue; 
ControlHandle control; 


GlobalToLocal(&where?; 

par tCode=F indControl(where, theWindow, &control); 

if (partCode==0) /*mouse down not in scroll bar*/ 
returnCFALSE); 


lineSizezGetCRef ConCcontro1); 
ifClineSize«2) /* horiz scrolling */ 
( linesVissscrlp- horizL inesVis; 
scrollTypesHorizBar; 
lineSizez-lineS ize; 


else /* vert scrolling */ 


( linesVissscrlp-?vertL inesVis; 
scrollTypesVertBar; 
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switch(partCode) 

( case inUpButton: 
case inDownButton: 
case inPageUp: 
case inPageDown: 

switchCpartCode) 

( case inUpButton: 
scrollAmtz-1; 
break; 

case inDownButton: 
scrollAmtz1; 
break; 

case inPageUp: 
scrollAmt--linesVis; 
break; 

case inPageDown: 
scrollAmtslinesVis; 
break; 


scrollCode-partCode; 
TrackControlCcontrol, where, &ScrollProc?; 
break; 

case inThumb: 
oldValue-GetCtlValueCcontro1); 
if (TrackControl(control, where, - 1L2) 
( newValue=GetCtlValue(control); 

ThumbMove( theWindow, 01dValue, newValue); 


break; 


default: 
break; 


return TRUE); 


/*Set to prepare for automatic scrolling of scroll bars 


- internal use */ 


SetSelectScrollCcontro1) 
ControlHandle contro!; 


lineSize-zGetCRef ConCcontro1); 
ifClineSize«0) /* horiz scrolling */ 
( linesVis-scrlp- hor izL inesVis; 
ӛсго11Туре-Ногі2Ваг; 
lineSize=-lineSize; 


else /* vert scrolling */ 
( linesVis=scr1p->vertLinesVis; 
scrollType-VertBar; 


scrollCode=0; 


) 


/*Scroll dir lines using scroll bar set by 
setSelectScroll - internal use */ 


SelectScroll(Cdir) 
int dir; 


scrollAmt=dir; 

if Cscrol] Type==Hor izBar 2 
ScrollProc(scrlp-?hScrollHd1,0); 

else 
ScrollProcCscr1p-?vScrollHdl,2); 


/*Scroll along with mouse while mouse button is down 
1. where: mouse location in Global coordinates 
Note: assumes scrolling in current active window */ 


DragScroll(where) 
Point where; 


77 


WindowPtr theWindow; 

register int vLineSizez0,hL іпе5іге-0 vAmt,hAmt; 
Rect dragRect; 

Point lastWhere; 


if Cscrl1p-?vScrollHdl!sNIL) 
( theWindowzC*Cscrlp-?vScrollHdl2)-?contrl0wner; 
vLineSizezGetCRef ConCscrlp-? vScrollHd1); 


if Cscrlp-^hScrollHdl!sNIL) 
( theWindows(*Cscrlp- hScrollHd122-»contrlOwner; 
hLineSizez-GetCRef ConCscrlp-?hScrollHd12; 


) 
if ((vLineSize==0)&&(hLineSize==0)) return; 


ScrollSectRectCscr lp, theWindow, &dragRect); 
Global ToLocal (&where ); 
if C!PtInRectCwhere, &dragRect)) return; 
lastWhere=where; 
whi leCStil1Down()) 
( GetMouseC&where); 
if (PtInRectCwhere, &dragRect )) 
( if(vLineSize»0) /* vert scrolling */ 
( if CvAmt=ClastWhere.v-where.v)/vLineSize) 
( SetSelectScroll(scrlp-?vScrollHd]); 
SelectScroll(vAmt); 
lastWhere.v-=vAmt*vLineSize; 


if ChLineSize>@) /* horiz scrolling x/ 
( if ChAmt=ClastWhere .h-where .h2/hL ineSize) 
( SetSelectScrol1(scr1p-»hScrol1Hd1); 
SelectScrollChAmt); 
lastWhere .h--hAmt*hL ineSize; 


) 
) 
) 
) 


/*Do joystick scrolling as long as mouse is down 
1. where: mouse location in Global coordinates 
Note: assumes scrolling in current active window */ 


JoyStickScroll(where) 
Point where; 


int vAmt,hAmt; 
Point newWhere; 


if CCscr1p-? vScrollHd12sNIL2&&Cscrlp-»hScrollHdl2sNIL 2) 


return; 

GlobalToLocal(&where?); 

whileCStillDownC2) 

( GetMouse(&newWhere); 
vAmt=CnewWhere.v-where.v)/vJoySpeed; 
if CCscr1p-> vScrol 1Hd1 ! =М№МІ &&vAmt) 

( SetSelectScroll(scrlp-?vScrol1Hd1); 
SelectScrollCvAmt); 


hAntzCnewWhere .h-where .h)/hJoySpeed; 

if CCser1p->hScrol 1Hd7 !=NIL &&hAmt) 

( SetSelectScroll(scrlp-?hScrollHd1); 
SelectScrollChAmt?; 


) 
) 


/*Set joy stick speed in pixels per speed increment 
1. v or hSpeed: vertical or horizontal settings */ 


SetJoySpeed(vSpeed, hSpeed) 
int vSpeed,hSpeed; 
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vJoySpeed=vSpeed; 
hJoySpeed=hSpeed; 


/*If mouse is outside content region, scroll 1 line 
towards mouse location and return TRUE, 
otherwise just return FALSE 
Note: assumes scrolling in current active window */ 


ак 


Point where; 
RgnHandle tempRgn; 
int followed-FALSE; 


GetMouse(&where); 
GetClip(tempRgn=NewRgn()); 
ClipRect(&thePort-,portRect); 


if(scrlp->hScrollHd]!=NIL) /* horiz tracking */ 
( if(where.h«scrlp-^»horizScrollRect. left) 
( SetSelectScroll(scrip-^hScrollHd); 
SelectScro11C-1); 
followed-TRUE; 


else if (where .h>scr1p->hor izScrollRect.right) 
( SetSelectScrol1(ser1p-»hScrol1Hd1); 
SelectScro11C15; 
followed-TRUE; 


ifCscrlp-»vScrollHdl!zNIL)  /* vert tracking */ 
( if(where.v«scrlp-»vertScrollRect.top) 
( SetSelectScrollCscrlp-?vScrollHd!); 
SelectScrol1(-1); 
fol lowed=TRUE ; 


else if(where.v?scrlp- vertScrollRect.bottom) 
( SetSelectScroll(scrlp-?vScrollHd1); 
SelectScro11C 1); 
fol lowed=TRUE ; 


) 


SetClip(tempRgn); 
DisposeRgn(tempRgn); 
return(followed); 


) 


/*Handle automatic scrolling of Text Edit Windows 
Note: assumes scrolling in current active window */ 


nad Boolean SMClikLoopC) 


Point where; 
RgnHandle tempRgn; 


GetMouse(&where ); 

if (PtInRectCwhere, &C**scr1p->hTE).viewRect)) 
return( TRUE); 

GetClip(tempRgn=NewRgn()); 

ClipRect(&thePor t-> por tRect); 


if(scrlp-»hScrollHdl!:NIL) /* horiz tracking */ 
{ if(where.h«C**scrlp- hTED.viewRect.. left) 
( SetSelectScroll(scrip-»hScrollHd1); 
SelectScrol1(-1); 


else if (where.h) (**scr1p->hTE).viewRect .right) 
( SetSelectScrol1(scr1p-»hScrol1Hd1); 
SelectScro11C1); 


) 
if(scrlp- vScrollHdl!sNIL)  /* vert tracking */ 
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( if(where.v<(**scrlp-xhTE).viewRect.top) 
( SetSelectScroll(scrl1p->vScrollHd1); 
SelectScroll(-1); 


else if Cwhere.v>(**scr1p->hTE).viewRect .bot tom) 
( SetSelectScrollCscrlp-?vScrollHd1); 
SelectScro11C15; 


) 


SetClipCtempRgn?; /* must restore clip region */ 
DisposeRgn( tempRgn); 
return( TRUE); 

) 


/*Scroll window from oldValue to newValue 
- internal use */ 


ThumbMoveCtheWindow,oldValue,newValue) 
WindowPtr theWindow; 
int oldValue,newValue; 


int units-oldValue-newValue; 


if Cunits) 
ScrollWindowCtheWindow,units); 
) 


/*Do the actual scrolling. When required this routine 
calls UpdateWindowC) which must be supplied by the 


application - internal use */ 


ScrollWindowCtheWindow,units) 
WindowPtr theWindow; 
int units; 


int absunits,rectLength; 
Boolean hasRuler=FALSE; 
RgnHandle tmpRgn; 
GrafPtr saveport; 

Rect rulerRect; 


GetPortC&savepor t); 
SetPort( theW indow); 
absunits= units<®@ ? -units : units; 


/* scroll text windows */ 
ifCserlp-^» hTE!zNIL) 
( if(scrolllupe==HorizBar) 
( TEScroll(rectLengthzlineSize*units, 0, 
scr ip^ hTE); 
if Cscrlp- vRectTopLeft.v!- 
scr lp-^»hRectTopLef t .v) 

( hasRuler=TRUE; 
rulerRect.left-scrlp-»hRectTopLeft.h; 
rulerRect.topsscrlp-^hRectTopLeft.v; 
rulerRect.bottom=scr1p->vRectTopLeft.v; 
rulerRect.right- 

scrlp-^horizScrollRect.right; 


) 
else 
( TEScro11(@,rectLength=1ineSize*units, 
scr l1p-^ ТЕ); 
if(scrlp-?vRectTopLef t.h!- 
scrlp-^hRectTopLef t .h) 
( hasRuler=TRUE; 
rulerRect.leftzscrlp- vRectTopLeft.h; 
rulerRect.top-scrlp-?vRectTopLef t. v; 
rulerRect .right=scr 1p->hRectTopLef t .h; 
rulerRect .bottom= 
scrlp- vertScrollRect .bottom; 
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/*if rulers in text windows, scroll them*/ 
if ChasRuler ) 
( tmpRgn=NewRgn(); 
if Cscrol 1 Type==Hor izBar ) 
ScrollRectC&rulerRect, lineSize*units,9, 
tmpRgn ); 
else 
ScrollRectC&rulerRect,2, lineSize*units, 
tmpRgn); 
InvalRgn( tmpRgn ); 
DisposeRgn( tmpRgn); 


) 


/*Scolling more than 1 page in graphic windows */ 
else if Cabsunits> linesVis) 
( 1((өсго11Туре--Ног izBar ) 
InvalRectC&scrlp-?horizScrollRect?; 
else 
InvalRectC&scrlp-?vertScrollRect); 


/*Fractional page scolling in graphic windows x/ 
else 
( tmpRgn=NewRgn(); 
if CscrollTypez-Hor izBar ) 
ScrollRect(&scr1p->hor izScrol1Rect, 
lineSize*units,@, tmpRgn); 
else 
ScrollRect(&scr Ip-> ver tScrol Rect, 
9, lineSize*units, tmpRgn); 
InvalRgnCtmpRgn); 
DisposeRgn(tmpRgn); 


/*1f required, call Update process */ 
if (Cscr1p->NTE==NIL)| lhasRuler) 
UpdateWindowCtheWindow, scrollTgpe); 


SetPort(saveport); 


/*Scroll the line and column numbers given by selLine 
and selColumn into view 
Note: assumes scrolling in current active window */ 


FixInsertPtCselLine,selColumn) 
int selLine,selColumn; 


if Cscr1p-?vScrollHdl!sNIL) 
MoveInsertPt(selL ine, VertBar ); 

if Cscr1p-»hScrollHdl!szNIL) 
MoveInsertPt(selColumn,HorizBar); 


/*Scroll begining of selection of Text Edit window into 
view 
Note: assumes scrolling in current active window */ 


FixTEInsertPtO 
( 


int selLine,selColumn=@, textLength, *line£; 
WindowPtr TEWindow; 

GrafPtr saveGraf ; 

register int thePt, jumpSize, 1іпе оок; 


if Cser1p-»HTE==NIL) return; 
if Cser1p-> vScro] 1Hd1!=NIL) 
TEWindow=(*(scr 1p-» vScrol 1Hd1 ))->contr 10wner ; 
else if(scrlp-xyhScrollHdl!=NIL) 
TEWindow-C*Cscrlp-?hScrollHdl22-?contrlOwner; 
else 
return; 
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/*Binaru search for current line */ return; 
theP t=(**scrlp-»hTE).selStart; /*Set up pointers*/ 
lineLook=(**scr 1p->»hTE).nLines; 
1 ine®=&(**scr lp->hTE). lineStarts{@]; 
if CthePt>=*C1ine@+lineLook)) — /*Check last line*/ 
sellinezlineLook- 1; 
else /*Call TEClick - call from here insures SMClikLoop Code 
( jumpSizezlineLook»» 1| 1; /*div by 2, but not 0*/ available. Meaning of parameters identical to 
lineLook--jumpS ize; Toolbox routine TEClick() */ 
whi leC jumpSize=jumpSize>> 1| 1)/*reduce jumpsize*/ 
( if CthePt<*C1ine®+1 ineLook)) ScrollTEClickCwhere, theShif t, hTE) 
lineLook-2 jumpS ize; /*look back*/ Point where; 
else if(thePt>=*(1ine@+l1ineLook+1)) Boolean theShift; 
lineLookt=jumpSize; /%1оок forward*/ TEHandle hTE; 


SetSelectScroll(scrollHdl); 
SelectScrollCunits); 


else 
{ selLine=lineLook; /*found line*/ ТЕСТ ickCwhere, theShif t, ТЕ); 
break; 
) /*If ScrollInfo in heap, dispose of pointer when done. 
) Do not call if ScrollInfo not іп heap*/ 


/*Find column by getting width of text from start of 
line to insertion point. */ 
if Cscrl1p-»hScrollHdl!zNIL) 
( GetPort(&saveGraf ); 
Se tPor tC TEWindow); 
HLockCC**scr1lp-»hTE) .hText2; 
textLength-thePt- 
(**scr]p- hTE2.lineStarts[selL ine]; 
selColumn-TextWidthC*CC**scrTlp- ^ hTE) ҺТех0, 
(**scrlp- ^ hTE?.lineStarts[selL ine], 
textLength); 
HUnlock(¢**scr1p->hTE).hText); 
selColumn/zC-GetCRef ConCscr 1p-? hScro11Hd12); 
SetPort(saveGraf ); 
) /*Set the refCon in ScrollInfo record */ 


DisposeScrollCtheScr 1p) 
ScrollPtr theScrip; 


DisposPtr(CtheScr 1p); 


/*Return the refCon in ScrollInforecord */ 


long GetSRef ConCtheScr lp) 
ScrollPtr іһе5сгір; 


return(theScrlp->refCon); 


/* Correct selLine in case scrolling line is smaller 
than text lineHeight */ 
if (GetCRefCon(scr1p-)vScrol1Hd1)< 
(**scrlp- hTE)D. lineHeight) 
( selLine=selL ine*(**scr 1p-»hTE). lineHeight/ 
GetCRef ConCscr1p-? vScrollHd12; 
if CselLine»GetCtlValueCscrlp-?vScrollHdl2) 
selLinetz1*CC**scrlp- ҺТЕ). lineHeight/ 
GetCRef ConCscr1p-? vScrollHd12); 


SetSRef ConC theScr 1p, sRef Con) 
ScrollPtr іһе5сгір; 
long sRef Con; 


theScr 1p->refCon=sRef Con; 


/*Return the current active ScrollPtr */ 


ScrollPtr ActiveScrollPtr() 
FixInsertPtCsell ine,selColumn); ( 


return(scr1p); 


/*Scoll one direction to bring point into view 
- internal use */ Listing: ScrollerMain.c 


Move Inser tPt(selStart,barType) 
int selStart, barType; 


/*Application Scroller, version 1.0 (August, 26, 1988) 


This application demonstrate features and use of the 
int curValue, theL inesVis, units; Scrolling manager 
ControlHandle scrol1Hd1; 

@ 1988 John A. Nairn, All Rights Reserved */ 
if (bar Type==Ver tBar ) 


( theLinesVissscrlp-?vertLinesVis; /*Includes from Lightspeed C */ 


scrollHdl=scrl]p-j)jvScrollHd1; #include <QuickDraw.h? 
#include «MacTypes.h? 
else ®include <FontMgr .h> 
{ {ће inesVis=scr1p->horizLinesVis; "include «WindowMgr.h? 
ѕсго1\на1=ѕсг1р-› ћсго11на1; 8include <MenuMgr.h> 


8include «TextEdit.h» 

8include «EventMgr .h> 
curValuesGetCtlValueCscrollHd1); *include «DeskMgr .h> 
if CselStart«curValue) "include «DialogMgr.h? 


units-selStart-curValue; 
else if(selStar t? CcurValue*theL inesVis- 12) 
units-selStart-curValue-theL inesVis* 1; 
else 
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8include «ToolboxUtil.tv 
8include «ControlMgr.h? 
®include "ScrollMgr.h^  /*Scrolling Manager header*/ 
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enum ( apple_menu=255,file_menu,edit_menu ); 

enum ( drawCursor=300,handCursor,jouCursor 5 

"define sample text 500 

"define about 4100 998 

define NIL OL /* Some constants */ 

8def ine RULERWIDTH 15 

#def ine TOOLWIDTH 20 

#def ine about item 1 /* Menu items */ 

enum ( new. windowz1,graphic.windowz3, text. edit. window, 
vert bar-6,horiz.bar,vert. rulerz9,horiz.ruler, 
vert. (001. Баг,һогі2. tool. bar,quitzs14 ); 


WindowPtr myWindow=NIL; /* Global Variables */ 
TEHandle muhTE=NIL; 

ScrollInfo scrollRecord; 

ScrollPtr ту$сг1р; 

Point polygon(2001; 

Rect dragrect; 

int window type-graphic. window, has. vBar-TRUE; 


int has_vRuler=FALSE, has. vToo1s-FALSE ,has. hRuler-FALSE ; 


int has_hTools=FALSE, has. hBar- TRUE ; 
int vRuler,vTools, hRuler,hTools, polySize=0; 


/* Main Program- Initialize and start event loop */ 
main) 


MenuHandle menu; 
Rect r; 


InitGraf C&thePort); 

InitFonts(); 

Ini tWindows(); 

InitCursor(); 

FlushEventsCeveryEvent, 0); 

InitMenusC); 

TEInit(); 

InitDialogs(@L); 

r=screenBits.bounds; /* Window dragging Rect */ 
SetRect(&dragrect,4,24,r.right-4,r.bottom-4); 


menu=Ge tMenuCapp e menu); /*DA menu*/ 
AddResMenu(Cmenu, ‘DRVR’); 

InsertMenuCmenu, 0); 

menu=Ge tMenu(f ile menu); /*File menu*/ 
InsertMenuCmenu, 2); 


CheckItemCmenu, window. type, TRUE); 
CheckItemCmenu, hor iz. bar, has. vBar?; 
CheckItemCmenu, vert. bar , has. hBar ); 
InsertMenuCGetMenuCedit menu2,0); /*Edit Menu*/ 
MaintainMenusC)?; 

do_about(); 

event_loop(); 


) 
/*Enable or Disable Edit Menu */ 
MaintainMenus() 
if (FrontWindow()==muWindow) 
( if(muhTE==NIL) 
Disableltem(GetMHandle(edit_menu),0); 
else 
Enableltem(GetMHandle(edit_menu),0); 
else 


Enableltem(GetMHandle(edit_menu),0); 
DrawMenuBar(); 


/* Maintain cursor according to window tupe, keus 
down, and mouse location */ 


MaintainCursorC) 
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KeyMap theKeys; 
RgnHandle drawRgn; 
Point where; 


if CFrontWindowCO! 2myWindow) 
return; 
else if (muWindow==NIL) 
InitCursor(); 
else 
( drawRgn=ScrollSectRgn(muScrlp,muWindow); 
GetMouse(&where); 
if (!PtInRgn(where,drawRgn)) 
InitCursor(); 
else 
( GetKeys(&theKeys); 
if((theKeus.Keu[1)k4)&&(theKeus.Keu[1]&1)) 
SetCursor(*GetCursor(jouCursor)); 
else if (theKeus.Keu[1]&4) 
SetCursor(*GetCursor(handCursor)); 
else if (muhTE!=NIL) 
SetCursor(*GetCursor( iBeamCursor 22; 
else 
SetCursor(*GetCursor(drawCursor 2); 


DisposeRgn(drawRgn); 
) 
/*Program main event loop */ 
(oe 


EventRecord event; 
Boolean valid; 
char theChar; 


while (1) 
( SystemTask(); 
MaintainCursor(); 
if CmyhTE!=NIL) TEIdle(muhTE); 
val id=GetNextEvent(CeveryEvent, event); 
if C!valid) continue; 
SwitchCevent . what) 
( case mouseDown: 
do- mouse. down(&event); 
break; 
case keyDown: 
case autoKey: 
theCharzevent .message&charCodeMask ; 
if Cevent . modif iers&cmdKey) 
( ifCevent.what!zautoKey) 
do-menuCMenuKey(C theChar 2); 


else 
( if CmyhTE!=NIL) 
( if (C**myhTE). teLength «32760) 
( TEKeyCtheChar , nyhTE); 
if CnyScr 1p-? vScro11Hd1!zNIL) 
бе(5сго11(ту5сгір, 
(**myhTE).nL ines, Ver tBar); 
FixTEInsertPt(); 


else 
SysBeep(10); /* TE full */ 


else 
SysBeep( 10); /* bad key down */ 


break; 
case updateEvt: 
do_update(&event); 
break; 
case activateEvt: 
do_activate(CWindowP tr Jevent .message, 
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event.modif iers&act iveF lag); 
break; 
default: 
break; 


) 
) 


/* Handle mouse down events */ 


do_mouse_down(Ceventp ) 
EventRecord *eventp; 


WindowPtr windowp; 


int place_type=F indWindowCeventp-? where, &windowp); 


Boolean theshift; 
KeyMap theKeys; 


switch(p lace_type ) 

( case inMenuBar: 
do_menu(MenuSe lect Ceventp-) where )); 
break; 

case inSysWindow: 
SystemClickCeventp, windowp); 
MaintainMenus(); 
break; 

case inContent: 
if Cwindowp !=FrontWindow( )) 
( SelectWindow(windowp); 

MaintainMenus(); 


else if Cwindowp==myW indow 2 


{ ifKDoScroll(windowp, eventp-? where )==FALSE ) 


( GetKeys(&theKeys); 
if CCtheKeys Key 1184 26% 
CtheKeys .KeyL 11& 12) 
JoyStickScrollCeventp-? where); 
else ifCtheKeys.Key[ 124) 
DragScrollCeventp-? where); 
else if CmyhTE==NIL) 
TrackPolyCeventp-? where); 
else 
( Global ToLocal(keventp-) where); 
if (PtInRectCeventp-> where, 
&(**mJhTE).viewRect)) 
( if Ceventp->modif iers&shif tKey) 
theshif t=TRUE; 
else 
theshif t=FALSE; 
ScrollTEClickCeventp-? where, 
theshif t, myhTE); 


else 
SysBeep( 10); 


) 


break; 
case inDrag: 


DragWindow(windowp,eventp-? where, &dragrect); 


break; 
cese inGrow: 
grow window(windowp, eventp-? where); 
break; 
case inGoAway: 
if CTrackGoAway(windowp, eventp-? where)) 
( do_closeCwindowp); 
MaintainMenus(); 


break; 


default: 
break; 
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/* Track mouse and draw a polygon - for Graphic windows*/ 


TrackPolyCwhere ) 


Point where; 


int Im, tm; 

Point lastWhere; 
Rect drawRect; 
RgnHandle drawkgn; 


Global ToLocal C&where ); 

ScrollSectRect(nyScr 1p, myWindow, &drawRect ); 

if C!PtInRectCwhere, &drawRect )) 

( SysBeep( 10);  /* illegal click location */ 
return; 


GetMargins(myScr1p,&Im, inPixels,&tm, inPixels); 

if CpolySize==8) 

( polygon[polySize].h=where.h+1m; 
polygon[polySize].v=where.v+tm; 


else if(polySize--200) 
( SysBeep( 10); 
return; 


drewRgn2ScrollSectRgnCmyScr 1p, nyWindow); 
SetClipCdrawRgn); 
PenMode(patXor); 


MoveToCpolygon[polySize].h-1m,polggon[polygSize].v-tm); 


LineToCwhere .h, where у), 
lastWherezwhere; 
whileCStillDownC2) 
( GetMouseC&where); 
if CPtInRgnCwhere, drawRgn)) 
( if(Cwhere.h!=lastWhere.h)| | 
(where.v!=lastWhere.v)) 
( MoveTo(polygon[polySize}.h-1m, 
polygon[polySize].v-tm); 
LineToClastWhere .h, lestWhere .v); 
MoveToCpolygon[polySize).h-1m, 
polygon[polySize]l.v-tm); 
LineToCwhere .h, where.v2); 
las tWhere=where; 
) 
) 
else 
( MoveToCpolygon[polySize}.h-1m, 
polyggon[polySize]l.v-tm); 
LineToClastWhere.h, lastWhere.v); 
Fol lowMouse( ); 


GetMargins(myScr 1p, &1m, inPixels, &tm, іпРіхе15); 


MoveTo(polygon[polySize].h-1m, 

polygon[polySize].v-tm); 
LineToCwhere.h,where.v); 
lastWhere=where; 


) 


) 
Movelo(polugon[poluSize].h-1m,polugon[poluSize].v-tm); 


LineTo(lastWhere.h,lastWhere.v); 

PenMode(patCopu); 

if(lastWhere.h,)drawRect.right) 
lastWhere.h=drawRect.right; 

if ClastWhere .h<drawRect. left) 
lestWhere .h=drawRect. left; 

if ClastWhere.v>drawRect .bottom) 
lastWhere.v=drawRect .bottom; 

if ClastWhere.v<drawRect. top) 
lastWhere.v=drawRect. top; 


MoveToCpolygon[polySize].h-1m,polygon(polySize].v-tm); 


LineToClastWhere .h, lastWhere.v); 
polygon[**polgSize].hslestWhere.h*1m; 
polygon[polySize].v=lastWhere.v+tm; 
ClipRect(&myW indow-> por tRect); 
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) DisposeRgn(drawRgn); 


/* Close the scrolling demonstration window */ 


do_close(windowp) 
WindowPtr windowp; 


if CmyWindow!=NIL) 
( if(muhTE!=NIL) 
( ZeroScrap(); 
TEToScrap(); 
TEDispose(muhTE); 


CloseWindow(windowp); 
myWindow=NIL; 
myhTE=NIL; 
) 
) 


/* Handle menu command events */ 


do_menu(command) 
( long command; 
int menu_id=HiWord(command); 
int item=LoWord(command); 
if (menu_id!=0) 
do_menu_item(menu_id,item); 


/* Do a menu command */ 


do. menu. itemCmenu. id, item) 
int menu.id, item; 


char item name[32]; 
int newCheck; 


switchCmenu_id) 
{ case apple_menu: 
switchCitem) 
{ case about_item: 
do_about(); 
break; 
default: 
GetItemCGetMHandleCmenu. id), 
item, item name); 
OpenDeskAcct( i tem. name); 
HiliteMenu(@); 
MaintainMenus(); 
break; 
) 
break; 
case file menu: 
Switch Citem) 
( case new. window: 
do_closeCmyW indow); 
myNewW indow( ); 
HiliteMenu(@); 
MaintainMenus(); 
break; 
case graphic_window: 
case text_edit_window: 
Check! tem(GetMHandle(file_menu), 
window_type, FALSE); 
window_type=i tem; 
CheckItemCGetMHandleCf ile_menu), 
window_type, TRUE); 
break; 
case vert_bar: 
newCheck=has_vBar= 1-has. vBar ; 
break; 
case horiz_bar: 
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newCheck=has_hBar= 1-has. hBar ; 
break; 

case vert. ruler: 
newCheck=has_vRuler= 1-һав. vRuler; 
break; 

case horiz.ruler: 
newCheck=has_hRuler= i-has_hRuler ; 
break; 

case vert_tool_bar: 
newCheck-has. vToo1s- !-has_vTools; 
break; 

case horiz tool. bar: 
newCheck=has_hT0o01s= 1-һа5. ҺТо015; 
break; 

case quit: 
do_closeCmyWindow); 
finish); 

default: 
break; 


ifCitem -vert bar) 
CheckItemCGetMHandleCf ile. menu), 
item,newCheck ); 
break; 
case edit_menu: 
if C!SystemEditCitem-1)) 
( switchCitem-1) 
( case undoCmd: 
break; 
case cutCmd: 
TECutCmghTE); 
break; 
case copyCmd: 
TECopu(muhIE); 
break; 
case pasteCmd: 
if(((1ong)(**muhTE).teLength+ 
Clong)TEGetScrapLen( ))<32768) 
TEPaste(myhTE ); 
else 
SysBeep( 10); 
break; 
case clearCmd: 
TEDe leteCmyhTE); 
break; 
default: 
break; 


/* reset scroll bar */ 
if CmyScr 1p-> vScro11Hd1 !=NIL) 
SetScrol1(myScr 1p, C**myhTE) .nLines, 
Ver tBar ); 


/* if needed, move insertion point */ 
if CCCi tem- 1)==cutCnd)| | 
(Ci tem- 1)==clearCmd)| | 
(Citem- 1)==pasteCmd)) 
FixTEInsertPtC; 


default: 
break; 


HiliteMenu(C0); 


/* Handle Update events */ 


do-updateCevent) 


EventRecord *event; 
WindowPtr up.windz(WindowPtrOevent-?message; 


UpdateW indowCup_wind, FALSE); 


/* Update the window */ 


UpdateWindow(up-wind,scrollTupe) 
WindowPtr up-wind; 
int scrollTupe; 


GrafPtr save_graf ; 


if Cup_wind==myW indow) 

( GetPort(&save_graf ); 
SetPortCup_wind); 
BeginUpdateCup_wind); 
ClipRect(&up_wind-» por tRect); 
EraseRect(&up_wind->por tRect); 
ifC!scrollTgpe) 
( DrawControlsCup_wind); 

ScrollDrawGrowIcon(myScr]p, up_wind); 


draw. content Cup. wind, scrollType); 
EndUpdeteCup. wind); 
SetPort(save_graf ); 
) 


/*Activate the window */ 


do_activateCact_wind, isactivate) 
WindowPtr act_wind; 
int isactivate; 


Rect r; 


SetPortCact_wind); 
if Cact_wind==myW indow) 
( Scrol]DrawGrowIcon(myScr 1p, act. wind); 
if Cisactivate) 
( ScrollActivate(muScr]p); 
if (nyhTE! NIL) 
( TEActivateCmyhTE); 
TEFromScrap( 2; 


) 
else 
( ScrollDeactivate(myScr1p); 
if (nghTE! sNIL2 
( TEDeactivateCmyhTE); 
ZeroScrepC); 
TEToScrap( ); 


) 
) 
) 


/* handle window growing */ 


grow-window(windowp,mouse_point) 
WindowPtr windowp; 
Point mouse-point; 


long new.bounds; 


InvalBars(windowp); /*invalidate scroll bars*/ 
if CCnew_bounds=GrowW indow(w indowp, mouse_point, 
&dragrect ))==0) 
return; 
SizeWindow(windowp, LoWword(new_bounds ), 
HiWord(new-bounds), (Boolean TRUE ); 


InvalBars(windowp); /*invalidate new scroll bars*/ 


GrowScroll(windowp2;/*update scroll bar window*/ 


) 


/* Open new scrolling exemple window */ 
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Rect r,wrect; 

int hLineSize-0,vLineSizez-0,vTotalLines-£; 

int vToolSizez£, vRulerSize-0,hToolSizez£,hRulerSize-£; 
int vScrollTopz0,hScrollLef t=8,hTotalL ines=0; 

Boolean includeText-FALSE; 

FontInfo theFont; 

Handle texthdl; 


r-screenBi ts . bounds; 

SetRect(&wrect,20,60,r .right-20,r .bottom-20); 

nyWindow-NewWindowCNIL , &wrect, “\pScrolling Example", 
1, documentProc, - 1L, 1, 0L 5; 


poluSize=0; 
SetPort(muWindow); 
TextFont(geneva); 
TextSize(12); 
/*Note: add 1 to ruler and tool widths for line*/ 
if(has_vRuler) vRulerSize=RULERWIDTH+1; 
if Chas_hRuler) hRulerSize-RULERWIDTH* 1; 
if Chas_vTools) 
( vToolSize-TOOLWIDTH* 1; 
hScrol lLef t2 TOOLWIDTH* 1; 


if Chas_hTools) 
( hToolSize=TOOLWIDTH+1; 
vScrollTop-TOOLWIDTH:* 1; 


if(has.hBar) hLineSize= 18; 

if Cwindow_type==graphic_window ) 

{ vTotalLines=hTotalLines=40; 
if Chas_vBar ) vLineSize= 18; 


else 
( if Chas_vBar ) 
( GetFontInfoC&theFont?; 
vLineSizeztheFont .ascent*theFont .descent* 
theFont . leading; 


vTotalL іпеѕ=0; 
if Chas -hBar ) 
hTotalLines=(wrect .right-wrect. lef t-vToolSize- 
vRulerSize-SBarWidth)/hL ineSize; 
includeText=TRUE ; 


/* Seto up scoll bars */ 

nyScrlp-SetScrollWindow(myWindow,&scrollRecord, 
includeText, vLineSize, vTotalL ines, vToolS ize, 
vRulerS ize, vScrollTop,hLineSize,hTotalL ines, 
hToolSize,hRulerSize,hScrollLef t, NIL); 


/*If text window, add some sample text */ 
myhTE=myScr 1p-? ҺЕ; 
if CmyNTE!=NIL) 
( texthd1=GetResource( 'GNRL ^, sample text); 
HLockCtexthd12; 
TESetTextC*texthdl, SizeResourceCtexthd12, myhTE); 
HUnlockCtexthd1); 
ReleaseResource(texthd12; 
if CmyScr1p-> vScrollHdl !=NIL) 
SetScroll(nyScr lp, (**myhTE).nLines, Ver tBar); 


/* Set current window tool and ruler flags*/ 
vTools=has_vTools; 
hTools=has_hTools; 
vRuler=has_vRuler ; 
hRuler=has_hRuler ; 


/* Draw the window contents */ 
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draw_content(windowp,scrollTupe) 
WindowPtr windowp; 
int scrollType; 


register int i; 
int lineSize=20, 1m, tm, tick,nexttick; 


int vtoolsize=0,htoolsize=0,xtick,ytick, vtotal,htotal; 
static char vertToo1s[111- (10, "V^, E? R^, 'T^,"^ 60071” 


0’, 0’, Е ^94); 

static char horizTools[ 1215 (11, H^, "0" , "R^, "I^, "Z^, 
е ^ "5 0’, 10% 4 67) 

static int length{8]=(8,5,8,5, 11,5,8,5); 

char nstr[20]; 

Rect drawRect,tempRect; 

RgnHandle drawRgn; 


GetMargins(muScrlp,k]m,inPixels,ktm,inPixels); 
ClipRect(NonScrollRect(muScrlp,windowp,kdrawRect)); 
if(vTools) vtoolsize=TOOLWIDTH; 

ifChTools) htoolsize-TOOLWIDTH; 


if CvToo1s&&C !scrol1Type)) /*vert tool bar*/ 
( MoveToCvtoolsize, drawRect. top); 

LineToCvtoolsize,drawRect .bottom); 

TextFaceCout] ine+bold+shadow) ; 

forCi=1; i«zvertTools[01; i++) 

( MoveTo(@,htoolsize+20*i ); 
LineToCvtoolsize,htoolsize+20*i); 
MoveTo(6,htoolsize+20*i-5); 
DrawChar(vertToolslil]); 


) 
TextFace(C0); 


if ChToo1s&&C!scrollTgpe)) /*horiz tool bar*/ 
( MoveToCdrawRect . lef t, htoolsize); 

LineToCdrawRect .r ight,htoolsize); 

TextFaceCoutine*bold*shadow); 

forCiz1;i«-horizTools([2]1; i++) 

( MoveToCvtoolsize*25* i, 0); 
LineTo(vtoolsize*25*i ,htoolsize); 
MoveTo(Cvtoolsize*25*i- 17, 15); 
DrawChar Chor izTools( i 12; 


) 
TextFace(C0); 


if CvTools&&hToo1s&&C!scrollTgpe2) 
markXC2,9,htoolsize,vtoolsize); 


if CvRuler&&hRuler&&C!scrollTgpe)) 
markXCvtoolsize,htoolsize, RULERWIDTH, RULERWIDTH); 


TextSizeC9); 

if CvRuler&&CscrollTgpe!zHorizBar 2) 

( vtotal=vtoolsize+RULERWIDTH; 
MoveTo(vtotal ,drawRect. top*htoolsize); 
LineToCvtotal,drawRect.bottom); 
drawRect . top=htoolsize+RULERWIDTH*hRuler ; 
ClipRectC&drawRect); 
tick=tm/72; 
nexttick=drawRect. top+72*tick-tm-72; 
whi leC(nexttick+=72)<=drawRect .bottom) 
( MoveTo(vtoolsize,nexttick); 

LineToCvtotal,nexttick); 
if (tick) 
( NumToString(Clong)tick,nstr); 
MoveTo(vtotal-StringWidth(nstr), 
nexttick+8); 
DrawString(nstr); 


ҒогСіз1;1<-7; i++) 
( MoveToCvtotal,yticksnexttick*9*i); 
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LineToCvtotal-length[ i ],gt ick); 
{іск++, 
) 


if (hRUlerk&(scrollTupe!=VertBar)) 
( htotal=htoolsize+RULERWIDTH; 
drawRect.top=0; 
ClipRect(&drawRect); 
MoveToCdrawRect . lef t*vtoolsize,htota1); 
LineToCdrawRect .right,htotal); 
drawRect.left-vtoolsize*RULERWIDTH*vRuler; 
ClipRect(&drawRect); 
{іск=1т/72; 
nexttick=drawRect.left+72*tick-1m-72; 
while((nexttick+=72)(=drawRect.right+8) 
( MoveTo(nexttick,htoolsize); 
LineTo(nexttick,htotal); 
if (tick) 
( NumToString(Clong tick, nstr); 
MoveToCnexttick-1-Str ingWidth(nstr), 
htoolsize* 19); 
DrawString(nstr); 


богСіз1;1<-7; i++) 
( MoveTo(xtickenexttick*9*i htota1); 
LineTo(xtick,htotal-lengtht i 12; 


tick**; 


) 
) 
TextSizeC12); 


if (muhTE==NIL) /*Graphic Window Update*/ 

( drawRgn=Scro]1SectRgn(myScr Ip, windowp?; 
SetClipCdrawRgn); 
MoveToCpolygon(].h-1m,polggon([£2]. v-tm); 
forCi=1; i<=polySize; i++) 

LineToCpolygonli].h-1m, polygonlil.v-tm); 

ClipRectC&windowp-?portRect); 
DisposeRgn(drawRgn); 


else /*Text Window Update*/ 

( ClipRect(&windowp- por tRect):; 
tempRect=(**myhTE).viewRect; 
TEUpdate(C&tempRect , myhTE); 


) 
/*Draw X in window */ 


narkXCbeginx, beginy, xwidth, ywidth) 

int beginx, beginy, xwidth, ywidth; 

( MoveTo(beginx,beginy); 
LineToCbeginxtxwidth, beginytywidth); 
MoveTo(Cbeginx, beginytywidth); 
LineToCbeginx*xwidth,beginy); 


/* Present about box and wait for mouse click */ 


oor 


DialogPtr aboutBox; 
EventRecord event; 


aboutBox=Ge tNewD ialog(about_dlog,NIL,-1L); 
DrawDialog(aboutBox); 


/* wait for key or mouse click - 
from MacTutor, Ү4,83,р010 */ 


whi Тес !EventAvai 1 CkeyDownMask | autoKeyMask |mDownMask, 


&event )) 


SustemTask(); 


if (event .what==mouseDown) 
( GlobalToLocal(&event.where); 


if CPtInRectCevent. where, &aboutBox-? por tRect 2) 


Ge tNex tEvent (mDownMask, &event ); 


) 


DisposDialogCaboutBox); 


/* Exit to shell after saving TE scrap */ 


f inishC) 
( 


ZeroScrap(); 
TEToScrap(); 
LoadScrap(); 
ExitToShel1(); 


Listing: Scroller Project.R 


ХХХХХХКЕХХКХХХХХХХЕХХХХХХХХХХХХХХАХ ХХХ ХХХ 
x 


* 


ж RMaker resource file source for * 
* Application Scroller x 

x x 

* @ 1988 John A. Nairn * 

x x 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Scroller Project.rsrc 
29999292 


Туре SCRL = STR 
0 


Demo of the Scrolling Manager - ++ 
August 13, 1988 


Type FREF 
, 128 
APPL @ 


Type BNDL 
, 128 

SCRL 0 
ICN* 

0 128 

FREF 

0 128 


Type MENU 
,255 (0) 
\14 
About Scroller.. 
(- 


; Apple Menu 


,256 (0) 
File ;;File Menu 
New Window /N 
(- 
Graphics Window 
Text Edit Window 

(- 
Vertical Scroll Bar 
Horizontal Scroll Bar 
(- 
Vertical Ruler 
Horizontal Ruler 
Vertical Tool Bar 
Horizontal Tool Bar 
(- 
Quit/Q 
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/* remove mouse down */ 


,251 (0) 
Edit 
Undo/Z 

(- 

Cut /X 
Copy/C 
Paste/V 
Clear 


Type DITL 
,998 
3 


;,Edit Menu 


;;Text for About Box 


StatText Disabled 
11 58 29 320 
Scroller (@ 1988, All Rights Reserved) 


StatText Disabled 
35 18 88 372 

This application demonstrates the ++ 
features of the Scrolling Manager ++ 
library of routines which can help ++ 
other applications easily accomplish ++ 
window scrolling. 


StatText Disabled 


93 87 175 


For information contact:\9D ++ 


288 


;,Number of items 


John A. Nairn\@D ++ 
7108 S. Pine Cone 5+. \00 ++ 
Salt Lake City, UT 84121V0D ++ 


(88 1)- 


Type DLOG 
, 998 

About Box 

62 62 250 


Visible NoGoAway 
3 


0 
998 


Type GNRL 
, 500 
H 


942-7768 


; , About dialog 


445 


;;Process ID 
;,refCon 


;;ltem list ID 


;;lext Edit window text 


2020 2020 2054 6865 2074 6578 7420 6564 
6974 696E 6728 696E 2074 6869 7320 7769 
2069 7320 6861 6E64 6C65 6420 


6E64 6F77 
6279 2074 
206D 616E 
T26F 6C6C 
6564 2062 
696E 6720 
2020 2059 
696E 2074 
2014 6865 
1061 7374 
2063 6Ғ60 
7365 6C65 
6F72 2065 
6F75 2064 
1468 6520 
5363 726F 
1220 7169 
616С 6679 
7169 6Е64 
2074 6865 
5363 726Ғ 
1220 616C 
6861 7420 
6Е20 6261 
6963 6166 
696Е 746Ғ 


6865 2054 
6167 6572 
696Е 6720 
7920 7468 
4061 6E61 
6F75 2063 
6578 742C 
2063 7574 
652C 2061 
6061 6Е64 
6374 696Е 
6469 7469 
7261 6720 
7169 6E64 
6C6C 696Е 
6C6C 2061 
2073 6372 
6F77 2074 
2060 6F75 
6C6C 696Е 
T36F 2069 
1468 6520 
1220 6973 
6С79 2013 
2076 6965 


6578 7420 
2Е20 5468 
6973 2068 
6520 5363 
6765 722Е 
616Е 2074 
2061 6Е64 
2020 636Ғ 
6Е64 2063 
732E 2057 
6720 7465 
6E67 2061 
6F75 7473 
6F77 2020 
6720 4061 
1574 6Ғ60 
6F6C 6C20 
6F20 666F 
7365 2Е20 
6720 4061 
бЕТЗ 7572 
696Е 7365 
2061 7574 
6372 6F6C 
7720 7768 


4564 6914 
6520 7363 
616Е 646C 
726Ғ 6C6C 
0000 2020 
1970 6520 
2075 1365 
1019 2026 
6C65 6172 
6865 6Е20 
1874 2066 
6Е64 2079 
6964 6520 
1468 6520 
6E61 6765 
6174 6963 
1468 6520 
6C6C 6F77 
5468 6520 
6E61 6765 
6573 2074 
7274 696Ғ 
6F6D 6174 
6C65 6420 
656Е 2061 
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1070 T26F 7072 6961 7465 2Е00 0020 2020 
2020 486F 6C64 696E 6720 646F 776E 2074 
6865 206F 7074 696F 6E20 6B65 7920 696D 
706C 6560 656E 7473 2064 7261 6720 7363 
T26F 6C6C 696E 672E 2048 6F6C 6469 6E67 
2064 6FTT 6Е20 7468 6520 7368 6966 7420 


616E 6420 
6960 706С 
1469 6368 


Type ICN# 
, 128 

.H 

FFFF FFFF 
A40A 4AA1 
8000 0111 
AADO QIFF 
ВІІЕ C183 
BE95 5145 
86BE A101 
AEA2 B525 
FFFF FFFF 
FFFF FFFF 
FFFF FFFF 
FFFF FFFF 


6F70 7469 6F6E 206B 
656D 656E 7473 206A 
2073 6372 6F6C 6C69 


6579 7320 
6F79 2073 
6E67 2E 


= GNRL ;;Application Icon 


8000 0001 BC18 00А1 
BDDB 4EAD 8000 0001 
8000 0139 8400 0170 
AEØØ 01АВ B100 0155 
A26F E183 BEEO ТІҒҒ 
A388 9929 A302 0911 
9563 6971 AEA2 B55D 
9563 693D 868E A101 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 


А503 6EAD 
FFFF FFFF 
AA00 0139 
ATIF BIFF 
BEC8 9129 
FFFF FFFF 
C563 6375 
FFFF FFFF 
FFFF FFFF 
FFFF FFFF 
FFFF FFFF 
FFFF FFFF 


FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF 


FFFF FFFF 
FFFF FFFF 


TYPE CURS 
,300 
H 


00Ғ0 0088 
0840 0880 
00Ғ0 00Ғ8 
ØFCO 0Ғ80 
0010 0003 


,301 
H 

0180 1A70 
8802 4002 
0180 1ВҒ0 
FFFE 7FFE 
0009 0008 


, 302 

.H 
0080 01C0 
3086 1084 
0000 0000 


FFFF FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF FFFF 


= GNRL 
; Pencil Cursor 


0108 20190 0270 0220 0420 
1080 1100 1Е00 1С00 1800 
01Ғ8 01Ғ0 03Ғ0 03Е0 07Е0 
ІҒ80 1Ғ00 1Е00 0000 0000 


;;Hand Cursor 


2648 264А 1240 1249 6809 
2002 2004 1004 0808 0408 
3FF8 3FFA IFFF FFF EFFF 
3FFE 3FFC IFFC ØFF8 07Ғ8 


j; JoyStick Cursor 


03Ей0 0080 0080 1084 3086 
0080 0080 03Е0 01С0 0080 
0000 0000 0000 0000 0000 


FFFF 
FFFF 


0440 
1000 
07C0 
0000 


9801 
0408 
FFFF 
O7F8 


TFFF 
0000 
0000 


0000 0000 0000 0000 0000 0000 0000 0000 


0007 0008 
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Programmer's Workshop 
April Fool's INIT: Scrolling the Menu Bar! ? 


Probably everyone who reads this magazine knows at least 
one person whoownsa Mac that they’d like to play a joke on. This 
INIT resource might be just the thing you’re looking for. It is a 
patch to_GetNextEvent that will scroll the menu bar off the right 
side of the screen (leaving the menu bar blank) when the mouse 
is clicked in the very top pixel of the menu bar with an odd 
horizontal position. It does nothing if the mouse is clicked 
anywhere else on the screen, so it is possible to use the menus 
when this patch is installed, just so long as you don’t click in the 
very top pixel at an odd position. The menus will come back 
eventually (after a few sarcastic messages are displayed in the 
empty menu bar), so this is a pretty harmless patch (although 
extremely annoying according to my guinea pig roommate). 
Command key equivalents for current menus (like COMMAND- 
Q) will work even though no menus are shown. It is possible to 
remove the patch once it is installed by typing COMMAND- 
SHIFT-OPTION-TAB. The patch will beep to let you know ithas 
been removed. 


HOW IT WORKS 

This patch to _GetNextEvent is an application of the tech- 
nique I used in the Shift Mod patch (September 1987 issue of 
MacTutor). It is a tail patch on _GetNextEvent that looks at the 
event being returned and intercepts it if it is a mouseDown event 
with a vertical position of zero and an odd horizontal position. 
When it finds such an event the menu bar is scrolled off the screen 
and then _DrawMenuBar and . HiliteMenu are patched to do 
nothing. The reason those two traps are patched is because we 
don’t want anything drawn in the menu bar while we’re display- 
ing our messages. The menu bar is restored by restoring those two 
traps and then calling DrawMenuBar. Note that because we are 
patching . DrawMenuBar the user will not be able to get the 
menus back by quitting the current application and/or launching 
another application (because every application uses 
_DrawMenuBar to put their menus up). 

Once we have scrolled the menus off, the patch to GetNex- 
tEvent will intercept any mouseDown event anywhere in the 
menu bar area and display a message in the menu bar for 1 second 
or until the mouse button is let go, which ever is longer. After four 
such messages, the patches to DrawMenuBar and  Hilite- 
MenuBar are removed and. DrawMenuBar is called to draw the 
current menu bar (which may not necessarily be the one that was 
scrolled off since the user could have changed applications in the 
mean time). 

To do the actual scrolling you would expect me to use 
_ScrollRect. That's what I tried at first, but it was too slow (took 
about 10 seconds for the menu bar to get all the way off the 
screen). Then I tried scrolling by 3 or 4 pixels at a time, but it 
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wasn't smooth enough. The version you see here is scrolling by 
rotating bits in screen memory (via the 68000's roxr instruction). 
Although somewhat unorthodox (Apple wouldn't approve) it 
now only takes about 2 seconds to smoothly scroll the menu bar 
all the way off the screen. 


PROBLEM 

There is a potential problem with this patch. There is a 
danger in patching and unpatching traps that may be patched by 
other applications. For applications that patch traps this isn't 
normally a problem because they get a chance to restore the traps 
when they quit (before something else can patch them). But it is 
possible for our patches to be unpatched at a bad time. A “bad 
time" to unpatch would be after something else has patched on 
top of one of our patches. For instance, if we patch _GetNextE- 
vent and then some other program patches itand then we unpatch 
ours, the second patch will be unpatched along with ours, but the 
application that made the second patch won't know about it. To 
partially correct this from happening, I have the removePatch 
routine check if something has patched _GetNextEvent after we 
have patched it (by calling GetTrapAddress and comparing it to 
ourself) and if it has, then ignore the request to unpatch ourself. 
I did not do this for DrawMenuBar and HiliteMenu, but it is 
unlikely that other applications would patch either of those two 
(besides, this is only a joke — it's not something you're going to 
leave around in your System Folder forever). 

One additional problem is that while this patch should work 
on any size monochrome monitor, it will not work on a Mac II 
color monitor. If anyone comes up with a simple fix, please send 
it in. 


— 


scrollMenuBarPatch.c 18 Nov 1987 


by Mike Scanlin and Andy Voelker 


x 

x 

x 

x 

* This will install а patch to 

* _GetNextEvent that intercepts 

* mouseDown events if they occur in the 
* very top pixel-row of the screen. If 
* an event is intercepted, the menu bar 
* is scrolled off the right side of the 
* screen before the user can react. 

* After 4 more clicks in the menuBar 

* (with appropriately sarcastic messages 
* displayed after each one) the origina 
* 1 menuBar is restored. The patch can 
* be removed by typing 

* COMMAND-OPTION-SHIFT-TAB. 

*/ 


#include “EventMgr .h” 
#include "QuickDraw.h"^ 
include “asm.h” 
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/* low memoru globals */ 


extern Handle MenuList : 0x0A1C; 
extern Ptr ScrnBase : 0x0824; 
extern GrafPtr WMgrPort : Ox@9DE; 
/* the traps we patch */ 

"define GetNextEventTrap 0хА970 
"define DrawMenuBarTrap @хА937 
"define HiliteMenuTrap 0xA938 
"def ine CLICKS. TO. MENU 4 

"def ine MESSAGE. DELAY 60 

"def ine МЕМ) ВАР. HEIGHT 20 

#def ine TAB. KEY 0x09 

8def ine | JMP. INSTRUCTION Qx4EF9 
"define memFullErr - 108 
"define screenBits_bounds_right -110 


8Sdefine sSscreenBits bounds. left-114 
voidmain(void); 
void main() 


asm { 


=“ 
зе 


This first section is the onlu рагі 
that gets run initiallu. It gets some 
space in the system heap and sets up a 
patch to .GetNextEvent. The patch 
won’t do anything until the user 
clicks in the very top pixel of the 
menu bar Cin which case it will scroll 
the menu bar off the screen to the 
right). */ 


є «е w * ж 34 ж м 


move.] D3, -CSP) 


/* get the old trap address */ 
move 8CGetNextEventTrap,D0 
-GetTrapAddress 


/* set the address for the JMP 

* instruction that calls the original 
trep */ 

lea eor igIrap,A1 

move.] A2,CA1) 


* 


/* get some space in the system heap for 
* our patch */ 
lea @last, Ad 
lea ӨГігеі,А1 
suba.1 А1,А0 
/* DØ = length of patch */ 
move.] Ай,00 
/* save length for .BlockMove */ 
move. | 00,03 


-NewPtr SYS 

cmp i 8SnemFullErr,DQ 
beq.s @noPatch 

lea @saveLoc, Al 


/* save for removePatch */ 
move. 1 AO, CA1) 

/* save for _BlockMove */ 
move. 1 AB, -CSP) 


/* set the trap address to the space we 
* just got in the system heap. */ 
move 8CetNextEventTrap,D0 
-SetTrapAddress 


/* now move our patch into place */ 


lea ef irst, Аб 
/* (SP)+ is the result from _NewPtr */ 
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поуе.1 ($Р)+,А1 
move. 1] 03,00 
-BlockMove 


@noPatch 
move. 1 CSP )+,03 


/* this is the end of the installation 
* part, but we can’t do an RTS here 
x because LSC needs to clean up. So we 
* fall through to the end. */ 

bra @last 


/ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖАЖЖЖЖЖЖЖЖ 
* Here's the new _GetNextEvent. It calls 
the existing .GetNextEvent and then 
checks if а mouseDown or keyDown event 
is being reported. If not, the event 
is pessed to the application 
unmodified. If we end up using the 
event ourselves, a null event is 


returned to the application. 
МАМА а 222224) 


ысым и и м 


@first 
/* pop the original return address and 
* save it */ 
lea &exitAddress, Аб 
move .1 (SP )+, CAB) 
/* save ptr to event record so we can get 
* at it later */ 
lea @eventRecPtr, Ad 
move. 1 (SP), CAB) 
/* set the return address to our patch */ 
pea @tailPatch 


/* the nops get filled with the address 
* of the original _GetNextEvent */ 
dc JMP_INSTRUCTION 
eor igTrap 
nop 
nop 


/* this is where it comes after the 
* normal _GetNextEvent processing */ 
@tailPatch 
movem.1 А1/00-О3,-(5Р) 


lea @eventRecPtr, Ad 
move. | CAB), AB 


/* check if it’s a keydown event that 
* says to remove ourself. This is the 
* only keyDown that we intercept. */ 


move 
OFFSETCEventRecord, what )(A0),D0 

cmpi ®keyDown, 00 

bne.s 6noKeyDown 


/* the key to remove the patch is 
* COMMAND-SHIFT-OPTION-Tab */ 
move.1 
OFFSETCEventRecord, message 2(А0),00 
cmpi.b 8TAB. KEY,DO 


bne.s @noKeyDown 
move 
OFFSETCEventRecord, modifiers (A), DØ 
andi 
норі ionKeytcmdKeytshif tKey, DO 
eor i 
8optionKey*cmdKey*sh if tKey, DØ 
beq.s @removePatch 
@noKeyDown 


/ if it’s not a mousedown event, then 


8 9 


* ignore it */ 
cmpi #mouseDown, 00 
bne.S épatchExit 


/* if we've already scrolled the menu 
* list, then don't scroll it again */ 


lea @menus, A1 
tst (А1) 
bne.s @alreaduGone 
/* if no menus exist, then leave */ 
тоуе.1 MenuList,A1 
move. | (A12,A1 
tst (A1) 


beq.s @patchExit 


/* if the mouse is not at an odd 
* location, then leave */ 


move. | 
OFFSETCEventRecord, where CAG), DØ 

andi 81/00 

beq.s @patchExit 


/* if the mouse is not at the very top 

* pixel of the menu bar, then leave */ 
move. | 

OFFSETCEventRecord, where (AQ), DØ 

/* put vertical coordinate in low word */ 
swap 
cmp i 81,00 
bge.s @patchExit 


/* now we’re set to scroll that puppy. */ 
bsr éscrollMenuBar 


/* save the fact that the menu ber that 
* was just scrolled */ 

lea @menus,A0 

move 81 (А0) 


/* patch .DrawMenuBar and .HiliteMenu to 
х do nothing if and when they're 
* called */ 


bsr edisableTraps 

lea @clicks,A1 

move #CLICKS_TO_MENU,(A1) 

bra.s @returnNullEvent 
@alreadyGone 


/* if mouse is not in menu bar, then 
* leave */ 
move.) | 
OFFSETCEventRecord, where )CAQ), DØ 
/* put vertical coordinate in low word */ 


swap 00 
cmp i ®MENU_BAR_HE IGHT, DØ 
bge.s @patchExit 
/* print a message in the menu bar */ 
bsr @drawAMessage 
lea eclicks,AQ 
subi 81, (AQ) 
bne.s @returnNul lEvent 


/* now that we’re finished playing, 
x restore .DrewMenuBar and 
* HiliteMenu */ 

bsr @restoreMenus 


@returnNul Event 


/* set the event to null */ 
lea GeventRecPtr , Ad 
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move. | CAB), AD 
clr 
OFFSETCEventRecord, what )CA2) 
/* change —GetNextEvent’s return value to 
* false. The 20 is for the 5 regs that 
* are saved on the stack at this point 
*/ 
clr 20(SP) 


@patchExit 

помет. (SP)+,A1/D0-D3 
/* JMP to the place that called 
x _GetNextEvent */ 

dc JMP. INSTRUCTION 
@exi tAddress 

nop 

nop 


/* this is where it comes to remove the 
* _GetNextEvent patch */ 

@removePatch 

/* if the menus aren’t shown, then 

* restore them before leaving */ 

bsr érestoreMenus 

/* check if we ere the most recent patch 
х to _GetNextEvent. If we're not, then 
* don^t unpatch. */ 


move tGetNextEventTrap,D9 
_GetTrapAddress 

lea ef irst, A1 

cmpa. | А1,А0 

bne.s @returnNul lEvent 


/* set the trap address back to the 
* original trap. */ 


lea Gor igirap, А0 

move. 1 CAB), AB 

move #GetNextEventTrap, 00 
-SetTrapAddress 


/* beep to let them know it has been 
* removed */ 


nove 81,-CSP) 
_5уѕВеер 
/* free up mem occupied by this patch */ 
lea @saveLoc, Ad 
move. | AB), AO 
-DisposPtr 
bra.s @returnNul lEvent 


/* This routine will disable _DrawMenuBar 
ж and _HiliteMenu */ 


@disableTraps 
move *DrawMenuBar Trap, 002 
_GetTrapAddress 
lea edrawMenuBarAddr , A 1 
move.1 A0,CA1) 
lea edoNothing, Ad 
move *DrawMenuBar Trap, DØ 
-SetTrapAddress 
move Hi liteMenuTrap, 00 
_GetTrapAddress 
lea ehiliteMenuAddr, A1 
move. | AG, CA1) 
lea @doNothingWi thParam, Аб 
move #HiliteMenuTrap, 00 
_SetTrapAddress 
rts 


/* This routine will restore .DrewMenuBar 
* and _HiliteMenu and then draw the 
* current menu bar */ 


@restoreMenus 
lea @menus , Ad 
tst (AQ) 
beq.S @doNothing 
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/* unpatch DrawMenuBar and then draw the 
* old menu bar */ 


lea @drawMenuBar Addr , Аб 
move. | CAB), AD 
move ®DrawMenuBar Trap, 00 
-SetTrapAddress 
lea &hiliteMenuAddr , Ай 
move. | CAB), AB 
move *HiliteMenuTrap, Dd 
-SetTrapAddress 
lea @menus , Аб 
clr (АЙ) 
-DrewMenuBar 

@doNothing 
rts 


/* This is the _HiliteMenu routine that 
* does nothing. It gets rid of the 
* parameter passed to _HiliteMenu and 
* then returns. */ 
@doNothingWithParam 
move. ] (SP)+,A0 
addq. | #2 SP 
jmp (АЙ) 


/* This is {ће routine that actuallu does 
* the scrolling */ 
6scrollMenuBar | 
/* hide the cursor so we don’t get part 
* of the cursor scrolled with the 
* menuBar */ 
-HideCursor 


/* get the current screen width from the 
* Quickdraw global screenBits */ 

move.] СА5 ),Аб 
/* 03 = # of columns (width) - 1 іп the 
* current screen */ 


move 

screenBits_bounds_right(A0),D3 
sub 

screenBits_bounds_lef t(A0),D3 
move D3,D2 
subq 81/03 


/* D2 = # of bytes - 1 in one screen 
* row */ 

asr 83,D2 

Subq 81,D2 


/* here's the loop that actually scrolls 
* the menu bar all the way across the 
* Screen */ 
@wayOut 
move ®MENU_BAR_HEIGHT - 2,01 


/* this outside loop will scroll all rows 
* of the menu bar one pixel to the right 
*/ 


@outside 
move 02,00 
addq 81,00 


/* calc 8 of butes from base addr to 
* start of current row */ 
mulu D1,D0 
move.1 ScrnBase, Аб 
adda. 1 DØ, AG 
/* white-out the left edge of this row */ 
clr.b (Ай) 
/* 00 = number of words іп one row */ 
move 02,00 
asr 81/00 
/* set the X flag */ 
andi.b ®OxEF,CCR 
/* this inner loop will scroll one row of 
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* the screen one pixel to the right */ 
@inside 

roxr (Аб )+ 

абга 00,біпсіде 


/* go and do the next row */ 
dbra D1,@outside 


/* make the corners look like they used 
* to Ci.e. rounded and black) */ 


move 02,00 

move.] ScrnBase,A1 
ori.b ®9xF8, CA1) 
adda 00,А1 

ori.b 80x1F,(A1)+ 
ori.b "OxEO, CA1) 
adda 00,А1 

ori.b 80x07, CA1)+ 
ori.b 80xCO, CA1) 
adda 00,А1 

ori.b 80x03,(A1)+ 
ori.b 80x80, (А1) 
adda 00,А1 

ori.b 80x01, CA1)+ 
ori.b 80x80, (А1) 
adda 00,А1 

ori.b #øxø1, (А1) 
dbra D3, @way0ut 
-ShowCursor 

rts 


/* this routine will print a string in 
* the menu bar, wait a bit and then 
* erase it */ 
@drawAMessage 
/* set the current port to the window 
* manager’s */ 
move. | CAD), Ad 
lea @savePort, A1 
move. 1 (A0),CA1) 
move.1 WMgrPort,(A0) 


/* save the old clipRgn */ 


lea @saveClip,A0 
move. | WMgrPort,A1 
move. | 


OFFSETCGrafPort,clipRgn)CA1), САЙ) 
/* set the clipRgn to be big enough for 
* the string we want to print */ 


subq 84 SP 
-NewRgn 
move.] WMgrPort, A1 
move. 1] 

CSP +, OFFSETCGrafPort,clipRgn)CA 1) 
pea @stringRect 
-ClipRect 


/* the string we print depends on the 
* value of the clicks variable */ 


lea @clicks, AQ 
move (А02,00 
cmpi 14,00 
bne.s 61 
реа @string1 
bra.s 65 

61 cmpi 83,00 
bne.s 62 
реа 6string2 
bra.s e5 

62 cmpi 82 DO 
bne.s e3 
pea estring3 
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bra.s @5 rts 


e3 cmpi 81,00 
bne.s @delau .&eventRecPtr dc.] 0 
реа @string4 /* @menus is TRUE while menus that exist 
85 move 810,-CSP) * are not being shown */ 
move 8 14,-CSP) @menus dc 0 
-МоуеТо @downT ime dc.1 Ø 
_DrawStr ing /* @clicks is the number of menus clicks 
@de lay * until menus return */ 
lea @downT ime , Аб @clicks dc 0 
move. | Ticks, (А0) /* @words is the number of 16 bit words 
* in one row of screen */ 
/* wait until the mouse is released or 60 @words dc 0 
* ticks, which ever is longer */ /* @saveLoc is the address of our patch 
@waitTilMouseUp * in the sustem heəp */ 
subq. 1 82 SP @saveLoc dc.] 0 
-StillDown @savePort dc.1 Ø 
tst (SP )+ @saveClip dc.1 Ø 
bne.s @waitTi 1Моџѕеур @drawMenuBar Addr dc.] Ø 
lea @downT ime, Ай @hiliteMenuAddr dc. 1 0 
move.1 (A0),D0 
addi.] #MESSAGE_DELAY,DO /* this rect should be big enough to 
cmp.1 Ticks, D8 * enclose the longest of the strings. */ 
bgt.s @waitTilMouseUp @stringRect dc 


0,8,MENU_BAR_HEIGHT- 1,300 
/* erase the string */ 


pea 6str ingRect /* define the pascal strings. Does LSC 
-EraseRect * provide a better way than this? */ 
estr ing1 dc.b 13 N 2, o, 
/* dispose of the clipRgn we created */ deu C usua rti du ЫР 
move.1 WMgrPort,A1 "psg 
move. | @string2 dc.b 14: *5^ ^t^, *1*, 
OFFSET(GrafPort,cl ipRgn)CA1),-CSP) АСОИ CT CS т”, 
-DisposeRgn "u^. s! 
/* restore the old clip rgn */ @string3 dc.b 7, N^, "o! t’, 
lea @saveClip, Ad в 
поме. 1 WMgrPort,A1 @string4 dc.b 25, 'W^, 'h', ’e’, 
move.] "p^ te^ " Шы ығы. ығы iud Buts ium 
CAG), OFFSETCGrafPort,cl ipRgn2CA1) “уе”, 1 Ие ^n! ^u^ ts"; 
[4 560,07. ^ ee 
/* restore the old port */ elast 
move.1 (А5),А0 - 
lea esavePort,A1 ) Seh 
move. | (А12,(А0) | аы» 
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C Workshop 
Segmenting DA's 


Segmented DAs: Breaking The 32K Limit 

In a variety of contexts on the Macintosh we find ourselves 
running up against “the 32K limit.” One area that has been 
particularly limiting and persistent is the 32K limit on resources 
containing code. The reason for this has to do with the way the 
MC68000 addresses memory; specifically one can address code 
within +32K (and the minus is generally ignored) of some base 
address very efficiently, so this mode is used for jumping to 
subroutines and for building jump tables. In particular, Light- 
speed C limits the code-containing resources it builds to 32K. 
This isn’ta big problem with applications, since one can break up 
the code in an application into multiple segments. This segmen- 
tation is actually nice in itself, since it allows programs that are 
too big to fit entirely in memory to run by swapping code 
resources in and out as needed. 

But Desk Accessories and stand-alone code resources 
(INITs, FKEYs, etc.) are a different story. The Mac OS has 
nothing built in to handle segmentation for anything but applica- 
tions, so we’re stuck with a 32K size limit. Fortunately, this can 
all be fixed up with a little inline assembler. I have been working 
with these sorts of things on several different projects, and have 
developed a fairly painless way of segmenting either DAs orcode 
resources. This is all done with stand-alone code resources, 
which I will call PROC’s. “Fairly painless” means: 

1) One shouldn’t have to write and debug a bunch of 
assembly code every time a PROC or routine is added to 
the project. 

2) APROC should be allowed to have multiple entry points. 
Further, accessible routines should be able to have differ- 
ent numbers of arguments. (A routine with a variable 
number of arguments is a bit trickier, but not an unreason- 
able variation on the code given below.) 

3) Lightspeed’s ability to check arguments types via func- 
tion prototypes should be left intact. 

3) Calling a procedure in an external PROC should be 
completely invisible to the calling C routine. 

4) It should be possible to have multiple entries into a code 
resource. That is, it should be possible to jump in and out 
of a given PROC, even to the point of allowing recursion 
between two PROCS. In short, there should be no more 
limitations in calling routines than exist in a normal 
segmented application. 

5) There should be a mechanism for loading and unloading 
PROCs the same way application code-resources are 
handled, or at least a reasonable approximation thereto. 


The biggest drawback of doing your own segmentation is 
that you have to handle part of the link yourself. Thatis, when you 
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make achange to one of the PROCs in a project, you have to make 
itaccessible to the “parent” code either by copying the PROC into 
the parent’s resource file, or by having the parent explicitly open 
resource file(s) containing the PROC(s). At the moment, I am 
working on a ShareWare DA that will make this process consid- 
erably less painful. 

The LSC documentation (2.01) supplement shows how to 
write “glue” to handle a single-entry PROC. Their code breaks 
down if you want to either call different routines within the 
PROC, or if there is a possibility of the PROC being called from 
two different places in the same call chain; more on this below. 
Working with all of this, I found out several interesting side 
effects of some ToolBox calls. For instance, PrJobDialog( and 
PrStlDialog() both go to the trouble of redrawing any dialog 
windows in the window list that need updating. This can really 
hose things if you have user item-drawing routines in a PROC 
that isn't setup to handle being called again before itreturns from 
the current call. 


The Big Issues 

There are three basic problems to solve. The first is how to 
handle multiple entry points. This is the easiest. The Mac PACK 
resources do this by tacking on an routine selector to the argu- 
ments for a routine within the PACK. Upon entry into the PACK, 
a bit of glue pulls the selector off of the stack and jumps to the 
right place. A variation on this theme will serve our needs. 

Next, LSC (and other environments such as Aztec C) allow 
non-application code resources to have globals by addressing off 
of register A4 instead of A5 (which is reserved for applications 
and QuickDraw). This means that upon entry into a PROC (ora 
DA) the value of A4 has to be set to the “correct” value to address 
the PROC’s globals. This is relatively easy; the tricky bit is to 
restore the old value when you exit so that whoever called you can 
still find their globals. The obvious solution (which LSC de- 
scribes) is to store the original value of A4 in a fixed location 
(actually, they use a pc-relative location, which can run afoul of 
the instruction cache in a 68020, but that's another story). This 
fails if the PROC gets re-entered from somewhere having a 
different value of A4, since we can only store one. 

The third problem has to do with handling the first two. The 
simple schemes for handling the first two problems involve three 
pieces of glue. The first handles putting the routine selector onto 
the stack and jumping to the (locked!) PROC. The next chunk is 
at the head of the PROC, it sets up A4, then uses the routine 
selector to jump to the desired routine. Finally, when the called 
routine is done, it can't just jump back to the caller; we must go 
through a last bit of glue to restore the callers's A4. Since, we 
would like to avoid tacking on this glue at every exit point of 
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every externally accessible routine, we want to doctor the return 
address to trick the called routine into returning to a third bit of 
glue which handles the clean-up. This means we have to pull the 
real return address off of the stack and store it somewhere. 
Storingitina fixed place leads to the same problems we had with 
A4 above. 


The Solution 

To avoid storing the two values which need to be saved and 
recovered in fixed locations, we will store them on the stack. We 
can’t store them below the arguments to the called routine, since 
then the routine will think it is getting two extra (long word) 
arguments, and this is supposed to be invisible to the C code. So 
instead, the first bit of glue shuffles the routine’s arguments down 
on the stack to make room for the 8 bytes of storage we need. We 
then replace the old return value with the address to the third bit 
of glue (which does the clean-up). We then jump to the second 
piece of glue which lives at the entry point to the PROC. It sets 
up A4 then pulls the selector off of the stack and jumps to the 
target routine. When the target routine “exits” the clean-up code 
retrieves the saved values, restores A4 then jumps back to the 
original caller. 

The details of implementing these ideas mainly have to do 
with doctoring the stack so that both the original caller and the 
target routine act exactly as if the usual JSR and RTS instructions 
were used to call and return from the target routine. (Remember 
this is all supposed to be invisible to the C code.) Care has to be 
taken to not attempt to address globals while A4 is holding the 
“wrong” value. We also cannot molest DO on the way back since 
that is where any return value is stored. 

There are a pair of routines which load and unload a PROC 
in the spirit of LoadSegment and UnloadSegment. To count as 
loaded, the PROC resource must be in memory, locked and 
marked unpurgeable. Unloaded is unlocked and purgeable (don’t 
actually ReleaseResource, in case we want it again). If these 
PROC’s are to be “owned” by a desk accessory, then we have to 
calculate the resource’s actual ID from the driver’s ID number 
and the sub-ID of the PROC. This is all handled by FLoadProc() 
and UnloadProc(). 

The following example is a stupid little DA which calls three 
routines in an external PROC with differing numbers of argu- 
ments and return values. Before doing so, it calls FLoadProc() 
which loads the PROC and stores a pointer to the PROC in a 
location passed to the routine. FLoadProc() calls MoveHHi() on 
the resource handle to reduce the possibility of causing fragmen- 
tation problems. When the DA is closed (which is the only thing 
that can be done to or with it), it calls UnloadProc() to unlock and 
free up the space used by the PROC resource. While debugging, 
it would be wise to set the pointer to the PROC to -1 when it is 
unloaded, so that if someone tries to use the unloaded PROC, an 
address error is immediately generated. This is really only an 
issue if PROCS are to be loaded and unloaded while the program 
is running to conserve memory (not an unlikely occurance, but 
remember that under LSC, globals are effectively re-initialized 
when a PROC is released from memory and read back in from 
disk). | 
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The second source is for the DA. It contains a bare bones DA 
with routines needed to load and call three routines in a PROC. 
There are also defines for the procedure selector numbers. These 
must begin at zero and occur in the same order as the jump table 
in the PROC. The glue to call a routine in a PROC consists of a 
"call" to an assembly language macro that does all of the work. 
Notice that the macro wants the number of WORDS passed as 
arguments to the routine, not bytes. Note also that this does not 
count the return address which also gets passed to the routine; the 
macro takes that into account. 

The first source file is for the PROC resource. It contains the 
entry glue for the PROC. Every routine that is to be externally 
callable has to have an entry in the JumpTable; see the note about 
routine selectors above. 

To build the PROC, create a new LSC project, add 
UselessProc.c, set its project type to "Code Resource,” its re- 
source type to ‘PROC’ and its ID to -16000 (sub ID zero owned 
by DRVR ID 12). Once created, the resource file is named 
UselessDAProj.rsrc so that it will be copied automatically into 
the DA file. In general, the PROC resource would have to be 
copied into the DA’s resource file. Note that you don't have to 
include MacTraps with this project (it does not call any routines 
defined there). 

After building the PROC, and giving its output file the 
specified name, create a new project called *UselessDAProj", 
add the first source file and MacTraps to the project, and build the 
DA.NowRunthe project (oropen the DA file with Suitcase), and 
open the DA. The DA will then put up a window (the first PROC 
call), write something funny in the window (the second PROC 
call). It will then wait until you close it, at which time it will get 
rid of its window (the third call to the PROC) and go away. Note 
that it does not handle even so much as activate or update events. 
Like I said, useless. 


For the Non-Hackers 

If assembly language is not your second language already, 
you're likely thoroughly lost. This should not prevent you from 
using the trickery here. Below is all you need to know to use the 
segmenting code. 

In the project that calls an external PROC, create a source 
module which contains the macro definition and a routine for 
each external procedure you wish to call. Pattern them after the 
routines OpenWindow(Q, DrawWindow() and KillWindow() in 
the DA source file. Each just calls the horrid assembler macro. Ве 
sure to count the words of arguments correctly, or things will die 
horribly. If you're not sure how to do this, consult your local guru. 
Next set up a main() in the PROC project patterned after the 
main() in UselessProc.c. Make one entry in the “JumpTable” for 
each routine you want to access. Then build a set of defines for 
the routine selectors (in the same order as they appear in the jump 
table). 


Potential Pitfalls 
The easiest things to mess up-are counting the words in the 
argumentlist. Remember that Pointers, Handles, Points, pointers 
to structs and arrays, and longs all count 2 words. Ints, shorts, 
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Booleans and chars all count 1 word (a char is only half a word, 
but gets passed as a word on the stack, this can be tricky and is 
probably compiler-dependent). Counting words in a struct or 
union can be tricky since bytes can get packed together, use 
sizeof() when in doubt. Don’t use sizeof(char), for the reason 
above. Next is mismatching the order of the routine selectors, 
check that one twice, too. 

Finally, the assembler macro assumes that the glue routine 
begins with a "LINK" instruction. This is true for any routine that 
has arguments or local variables. If you want to call an argument- 
less routine in a PROC, give its glue routine a dummy local 
variable to force a LINK instruction (LSC talks about LINKs on 
page 9-2 of the original manual). Alternatively, one could create 
another version of the macro with the UNLK statement removed 
for functions with no arguments, but this would leave two chunks 
of assembler code to maintain. 


Debugging Advice 

Although I have been using the code for some time and have 
written it very carefully, if you hit an inexplicable bug while 
using it, you're going to have to be convinced that the segmen- 
tation glue is not at fault. Besides, there is always a chance that 
I have made some subtle oversight. So, here is some advice for 
verifying that it's working correctly, or finding out why it is not. 

If you haven'talready, read LSC's explanation of MacsBug, 
and the C calling conventions, print out the source for all of the 
assembler hacking and dive in. If necessary, turn on “MacsBug 
Symbols" under the Options and recompile the relevant modules 
so that you сап see routine names. The best place to start watching 
things is just before the call to the glue routine. Watch the 
arguments as they are pushed onto the stack, step through the glue 
(not as messy as it sounds), and into the PROC. Make sure the 
right entry in the jump table is used. As soon as you hit the LINK 
statement that begins the target routine, do an “mr” (magic 
return) in MacsBug. You should then break out in the clean-up 
glue. Step through it and you're back to the caller. The Heap 
Dump command “hd” is useful for verifying the integrity of the 
application heap and that the PROC (and its caller!) are correctly 
loaded into memory, locked in place and unpurgable, use it 
liberally. It's a good idea to write down the state of the stack, the 
values for A4 and the return value as the glue is entered for 
comparison with things before and after the routine in the PROC 
is called. 


The Upshot 

This stuff is quite simple and reliable to use once properly set 
up. By creating multiple PROCS with different sub-IDs, there is 
virtually no limit to how much code a DA can address (pardon the 
pun). Routines can even be called directly between PROCs, 
making it possible to put libraries in PROCS for everyone to use. 
The only trick is calculating the PROC resource ID, since only 
the sub ID is known at compile time. The easiest way around that 
problem is to call an initialization routine for each PROC needing 
to make inter-PROC procedure calls which stores the base ID in 
a global. 
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Listing Useless.c 


* include 
* include 
*include 
*include 
* include 
* include 
*include 
*include 
* include 


яде? ine 


«MacTypes .h> 
«MemoryMgr .h> 
«Quickdrew.h» 
<WindowMgr .h> 
«EventMgr .h> 
«0SUtil.h» 
«ResourceMgr .h? 
«ToolboxUtil.h»? 
«DeviceMgr .h> 


NULL (ØL) 


8def ine drvrOpen 0 
Sdefine drvrPrime 1 
8def ine drvrContro12 
def ine drvrStatus 3 
define drvrClose 4 
"define subidProc 0 
enum ( 


2 


extern short 
extern short 
extern short 


irtnOpenWindow = 0, 
irtnDrawWindow, 
irtnKillWindow 


main(CntriParam*,DCtiPtr, short); 
DAOpenCCntr IParam*, DCt Ptr); 
DACloseCOntr IParam*,DCt Ptr); 


extern WindowPtr OpenWindowCchar*, short,short,short,short); 


extern void 
extern void 
extern Boolean 
extern void 


Ptr 


DrawWindow(WindowPtr, char*); 

Kil 1WindowCWindowPtr ); 
FLoadProc(short,Ptr*); 

UnloadProc(Ptr); 


pProc; 


short rsidBase; 


Sdefine | JumpToProc(pPROC, irtn, cwArgs) 
asm { \ 
unlk аб /* get rid of LSC’s frame ж/қ 


movea. | 
lea 


5р,ай /* address of ist argument */\ 
-8(5р),ѕр /* make room on the stack */\ 
movea.] sp,al /* bottom of stack */\ 
move.w — CcwArgs2*1,d0/*C*t of words to copy)-1*/\ 
/* copy rtn addr and arguments %7 


LCopyAnother : 
move.w (a@)+,(ai)+/* move a word down */\ 
dbra d@,@LCopyAnother/* done when -dð == -1*/\ 
move.]  84,Cal)* /% copy our a4 into storage*/\ 
томе.1 (sp)+,€ai) /* copy our гіп addr just behind it*/\ 
\ 
pea &LReturnToCaller/* push return for proc*/\ 
move.w #irtn,-(sp)/* push routine selector*/\ 
move.] pPR0C,-(sp)/* push address of PROC*/\ 
beq.s &LHandleError/* jump if passed a NULL pPROC*/\ 
LJumpToProc: \ 
rts /* jump to proc(sleazy trick) */\ 
LHandleError : A 
dc.w — QxAOFF /* let Macsbug “handle” the error*/\ 
lea lüCsp),sp/* fix up the stack STN 
\ 
LReturnToCal ler: 
\ | 
lea — (2*CcowArgs2)Csp2,80/* get add of storage space*/\ 
movea. | (ай )+,а4 /* restore our a4 x 
movea. | (a0),80 /% get our return address*/\ 
lea 8(sp),sp /* fix up the stack */\ 
x (a£) /* return to sender (address known)*/\ 


short main(piopb, расе, drvrRoutine) 
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CntrlParam *piopb; 
DCt]Ptr pdce; 
short drvrRoutine; 


GrafPtr pgpsav; 
short valRtn; 


if (pdce->dCtiStorage == NULL) { 
if (drvrRoutine == Ø) ( /* open, but no data */ 
SysBeep(3); 
CloseDr iver (pdce->dCt1Ref Num); 


return(d); 


GetPort € &pgpSav ); 


switch (drvrRoutine) ( 

case drvrÜüpen: 
valRtn = DAOpen(piopb, pdce); 
break; 

case drvrControl: 

case drvrPrime: 

case drvrStatus: 
valRtn = 0; 
break; 

case drvrClose: 
valRtn = DAClose(piopb, pdce); 
break; 


SetPort ( pgpSav ); 
return valRtn; 
) /* main */ 


short DAOpen(piopb,pdce) 
Спїг1Рагат *piopb; /* pointer to parameter block */ 
DCtIPtr pdce; /* the device control entry */ 


rsidBase = 0хС000 | (^pdce-»dCtlRefNum««5); 


if С !FLoadProc € Ø, &pProc ) ) ( 
SysBeep(2); 
CloseDriver(Cpdce-? dCt Ref Num); 
return 0; 


/* Using hard-wired window coordinates? For shame... */ 
расе-› dCt1Window=OpenWindow(”\POur Window", 100,50, 309, 150); 


(CWindowPeek )pdce-> dCt 1Window2-? windowKind-pdce-? dCt IRef Num; 


DrawWindowCpdce-?dCt Window, “\PSomething funny.^); 
return 0; 

) /* DAOpen */ 

short DAClose(piopb,pdce) 

CntrlParam *piopb, 

DCtlPtr pdce; 


` 
if С pdce->dCtlWindow != NULL ) 
KillWindow € pdce->dCtlWindow ); 


if ( pProc != NULL ) 
UnloadProc ( pProc ); 
) 


Boolean FLoadProc ( subid, ppProc ) 
short subid; 

Ptr *ppProc; 

( 
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Handle hProc; 


hProc = GetResource ( ‘PROC’, rsidBase + subid ); 
1f ( hProc == NULL ) ( 

*ppProc = NULL; 

return FALSE; 


/* avoid fragmentation and other evils */ 
MoveHHi ( hProc ); 
HLock ( hProc ); 
HNoPurge ( hProc ); 
*ppProc = *hProc; 
) return TRUE; 


void UnloadProc С pProc 2 
”" pProc; 


Handle hProc; 


1f С pProc == NULL ) 
return; 


hProc = RecoverHandle ( pProc ); 
і? С hProc == NULL ) 
return; 
HUnlock ( hProc ); 
HPurge ( hProc ); 
return; 


) 


WindowPtr OpenWindow C stTitle, xLeft, gTop, xRight, uBottom ) 
char stTitle(1; 
short xLeft, ylop, xRight, yBottom; 


JumpToProc(pProc, irtnOpenWindow,62; 


void DrawWindowC(pwind,st) 
WindowPtr  pwind; 
char stl]; 


JumpToProc(pProc, ir tnDrawWindow, 4); 


void KillWindow(pwind) 
WindowPtr  pwind; 
( 


JumpToProc(pProc, irtnKillWindow,2); 


Listing: UselessProc.c 
include “Maclupes.h> 
Sinclude <MemoryMgr .h? 
Sinclude <Quickdraw.h> 
$include <WindowMgr .h? 
8$include <EventMgr .h> 
Sinclude <OSUtil.h» 
Sinclude <ResourceMgr .h> 
Sinclude <ToolboxUtil.h 
Sinclude <DeviceMgr .h> 


Sdefine NULL (COL) 

extern void main С void ); 

extern WindowPtr OpenWindow С char*, short, short, short, 
short ); 


extern void DrawWindow ( WindowPtr, char * ); 
extern void KillWindow С WindowPtr ); 


void maint) 


asm { 
поуеа.1 ай,а4 ; get pointer to our globals 


© The Best of MacTutor, Vol. 5 


move.w (а72%,00 ; pop off routine selector 


add.w 00,40 ; double the selector void DrawWindow ( pwind, stMessage ) 
add.w 00,00 ; double it again WindowPtr pwind; 
lea @JumpTable,a; get address of jump table char  stMessage[]; 
jmp ØCað,dð.w) ; jump to our entry 
JumpTable: short h, v; 
jmp OpenWindow 
jmp DrawWindow SetPort € pwind ); 
jmp KillWindow v = (pwind->portRect.top + pwind-»portRect.bottom)/2; 


h = (pwind->portRect. left + pwind->portRect.right)/2; 


) h -= StringWidth(stMessage)/2; 
WindowPtr OpenWindow ( stTitle, left, top, right, bottom ) Movelo ( h, v ); 
cher stTitle[1; DrawString ( stMessage ); 
short left, top, right, bottom; ) 

Rect rect; void KillWindow ( pwind ) 

WindowPtr  pwind; 

SetRect ( &rect, left, top, right, bottom ); C | | 

return NewWindow(NULL, &rect,stTitle, TRUE, documentProc, - DisposeWindow С pwind ); 
IL, TRUE, ØL); ) 
) 
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Programmer's Forum 
Change the Boot Disk Icon 


I've been asked several times how my bootDiskIcon INIT 
works. I told the questioners that I’d answer in MacTutor. 

Also, this is a short article. MacTutor needs more of them 
— I know how to initialize Managers and handle events, and I 
certainly don’t need to see pictures in hexadecimal. (This isn’t 
just a snide remark directed at the editor, it’s a plea to those with 
nifty ideas that don’t need an entire application to show them off. 
Write a one or two page article!) 

bootDiskIcon is a hack that came about because I don't own 
an HD20. Apple insists on portraying their internal hard disk as 
an HD 20 on my desktop. I got so disgusted with this that I wrote 
an INIT to show something else, anything but an HD 20. ICN# 
256, in fact. bootDiskIcon is inferior to programs like Facade— 
it's less flexible, and may not work with all hard disks — but it 
was better than nothing, and it's easy to understand. 

The key to bootDiskIcon is the way the Finder handles disk 
icons. A pedantic digression: how does one find out how Finder 
handles icons? It's not in /nside Macintosh. Therefore, it must 
be in a Technical Note. But Finder isn't a category in the table 
of contents. So it's off to the index...but it's not listed under 
"icon." Luckily, it was one of the "Finder" Tech Notes, number 
28. How did I know to keep looking? Because I'd seen it years 
ago when it came out, and knew it was there somewhere. Always 
skim every Tech Note — not to memorize them, but to remember 
that they're there. 

When the Finder wants a disk icon, it gives the disk driver a 
Control call with csCode = 21. The driver returns a pointer to an 
ICN#. My first inclination was, why write code when you can 
change data? The ICN# must be part of the disk driver. The disk 
driver is part of Apple HD SC Setup. I found ii there (it’s not a 
resource), changed it, and reinstalled the driver. This failed 
utterly — there's apparently a checksum. 

If Icouldn't change the ICN? on disk, how about changing 
itin memory? Ican getits address in memory by giving the driver 
a csCode = 21 call, then simply change the data. This is what 
bootDisklcon does. 

Before I get to what you're all waiting for, the source code, 
I'll mention the difference between patches and INITs. A patch 
isa change to a piece of code, almost always one of the traps. Ап 
INIT resource is any piece of code that runs at startup time 
(typically ina file of type INIT, cdev, orrdev). An INIT frequent- 
ly installs a patch, but it could do anything at all, like playing a 
tune or subverting a disk driver’s icon. 

More ideological baggage: INITs should announce their 
presence. Paul Mercer has a good way to do this, called 
ShowINIT. I'm told the source code’s available on AppleLink. 
I’ve modified it to handle color icons, and compiled the whole 
thing as a separate resource, SHOW 0. bootDiskIcon calls this 
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bootDisklicon 


code. You’re welcome to use it in any non-commercial (free or 
shareware) programs — just use ResEdit to paste SHOW 0 into 
your own INIT file. You may not use it in public domain pro- 
grams. These are those without a copyright holder, and I don’t 
want my code in the public domain. Don’t make the mistake of 
calling your free program “‘public domain.” Once you do, you 
can’t get it back (despite what Adobe thinks). 

We can almost get to the code, but you might be wondering 
how to test it. It’s real inconvenient to reboot, just to see if a 
change worked. Luckily, you don’t have to. Remember that an 
INIT is just a piece of code that happens to get executed at boot 
time. You can often execute the same code at any time, and 
instruct your development system to make an INIT resource 
when you're finished debugging. In bootDiskIcon’s case, I 
simply executed it, juggled into the Finder layer, and verified that 
I'd changed the disk's icon. 

OK, you want the code. It starts out by calling my SHOW 
resource — the parameters are reversed from the way they're 
defined because my ShowICON is defined as a Pascal procedure. 
My sloppiness in not defining it as such in this C program 
probably works only because this is an INIT — if I trash the stack, 
it doesn't much matter, since ГІ be returning to INIT 31 very 
Soon. 

The real work begins with finding out the driver refNum and 
drive of the first mounted disk (now you know why it's called 
bootDiskIcon — I told you it was a quick hack). I then find the 
address of the driver's ICN#, get an ICN# of my own choice, and 
overwrite the driver's using BlockMove. 


8include <deviceMgr .h> 
®include «hfs.h? 


"def ine NILOL 


void main(void); /* Always use prototypes! */ 
void main() ( 
Ptr icn; 
int error;  /* Shouldn’t really be write-only.. */ 
HParamB lockRec pb; 
cntriParam cpb; 
Handle handle; 


/* Show icon on the bottom of the screen */ 
handle = GetResource( SHOW ,@); /* Get handle to the PROC */ 
if (handle == ØL) ( /* Something’s wrong Ccouldn't load) */ 


SysBeep(32); /* Let somebody know */ 
return; /* Don’t try to call it! */ 
HLockChandle); /* Hold down the PROC */ 


(**CProcPtr. *)handle)(-1, 128); 

/* ShowICONC) - note reversed parameters */ 

HUn lock Chandle); /* Let it float in the heap again 
*/ 
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/* Change the icon */ 

pb.volumeParam. ioNamePtr = NIL; 
pb.volumeParam. ioVolIndex = 1; /* First mounted volume */ 
error = PBHGetVInfoC&pb, FALSE); 

cpb. ioRefNum = pb.volumeParam. ioVDRef Num; 
cpb. ioVRefNum = pb.volumeParam. ioVDrvInfo; 
/* drive CioDrvNum) */ 

cpb.csCode = 21; 

error = PBControl(C&cpb, FALSE); 

icn = *(Ptr *)(&cpb.csParam[21); 

handle = GetResource( ‘ICN®’, 256); 
BlockMove(*handle, ісп, 256L 2; 
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Known Bugs 
Actually, these are rumored bugs, because it works for me! 
I’m told it doesn’t work with Jasmine disks where the driver puts 
the SCSI ID inside the flower. It probably doesn’t work with a 
boot floppy, because the Finder normally special cases the disk 


icon. (Furthermore, Finder probably doesn’t consider floppies to 
be “foreign drives.”) 


бм! 


«ы» 
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HindCight 
Lisa's Hourglass Is Back! 


Back to the Future: 
The Lisa's hourglass cursor comes to life 

In the rivalry between Lisa and Macintosh at Apple, many 
Lisa features weren'tcarried over into Mac development: a large 
screen, multi-tasking, stationery pads, virtual hardware, a huge 
keyboard... Now that these features are slowly reappearing in 
Macs, it's time to bring back one more dead Lisa feature — the 
hourglass cursor — and also breathe a little life into it. (Let's just 
not bring back rectangular pixels.) 

This article actually shows you the low-level mechanics of 
three kinds of animated cursors: 

• aone-handed watch, a simple sequence of ordinary cursors 

° a two-handed watch, built by combining cursors 

* an hourglass with falling sand: “drawn” by the application 

There's been a lot of discussion (see Further Reading) of 
whether an animated cursor should be done by a VBL (timed) 
task so the main program doesn't have to keep calling it. When 
I originally wrote these routines some years back (in MDS 
assembler), I made them a VBL task. I'm no longer sure that's 
a good idea. So this package doesn't animate on its own, but it 
should be easy to write a timed task to call them. 


Some notes on VBL cursor animation 

In case you do want to make the cursor run on its own, here 
are some things to keep in mind. (Thanks to Seth Lipkin for 
telling me about a number of these surprises...) 

* Remember that when a VBL task wakes up, the globals 
pointer (A5) isn't guaranteed and memory management can't be 
performed. Further, under MultiFinder, the СштепіА 5 variable 
may hold someone else's A5! You should store your AS, if you 
need it, adjacent to your task's VBL entry. 

° There's a low RAM location called CrsrBusy. As І 
understand it, when this byte is non-zero, you shouldn't do a 
SetCursor — I suspect it means there's a SetCursor already in 
progress. If your VBL task sees this flag, it should probably just 
try again in one tick. 

* The low-memory CrsrVis flag is cleared when the cursor's 
not visible (it's been hidden or temporarily obscured). Again, 
call back later. 

* Probably the biggest problem with VBL tasks is that they 
keep running no matter what. If your application locks up, the 
user will still see some life, and may not realize what's going on. 
If you must use the VBL trick, you might consider making the 
same task function as a watchdog timer", trying to figure out if 
the application is doing anything. If the application fails to bump 
some counter at least every n seconds, the task could hint at this 
with a different cursor. It's very risky to tell the user any other 
way, since any dialog would mean memory management. (I'm 
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Figure 1. Details of building the hourglass 
not sure if a VBL task can use the Notification Manager...) 


Drawing methods 

So if this package isn’t going to run the cursor on its own, 
what good is it? Well, it does various kinds of drawing, from 
simple to tricky. Each of the three cursor types has a different 
drawing method. 

The watch cursor functions a lot like the Finder’s. There’s 
a single list of cursors which are shown in a cycle. This could be 
done with a Finder-style ACUR resource, but if you want to do 


2000900000000 


00000020250 


Figure 2. Components of watch cursor 


the animation with a timed task, you don't want to do GetRe- 
source calls. (Actually, you could load the resources and make 
them non-purgeable before starting. But another reason is that all 
the data used by this watch is also used by the two-handed 
variant.) 

There are 12 frames to this animation sequence, shown in the 
top part of Figure 2. 


DOD 


Figure 3. Assembling a two-handed watch 
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The two-handed watch is only slightly more complicated. It 
uses two sets of data, one for the minute hand and one (in the 
bottom of Figure 2) for the hour hand. The hour hand has only 
8 positions; I couldn't draw 12 hands that small and keep it 
looking nice. So don’t worry if it looks like “four-thirty o'clock". 

Figure 3 shows how the hour and minute hand are logically 
“or”-ed together to make a two-handed watch. Like a real clock, 
the hour hand's position advances only once per revolution of the 
minute hand. 

The hourglass is alot more complicated. Looking at parts of 
Figure 1 shows some examples of how a grain of sand, a black 
pixel, moves: Atany given time, a single grain of sandis moving 
(a). When it lands on top of another grain (b), it randomly falls 
to one side or the other (c). If it lands with only one side open (d), 
it falls to the open side (e). If itlands with several steps to fall (f), 
it falls all the way until it doesn't have an opening on either side 
below (g). [Note that the bottom line of the hourglass must 
already be solid black pixels, or the sand will try to “leak out".] 
Finally, when a grain of sand drops as far as it can, and it's above 
acertain level (h), the bottom chamber is full, and the cycle starts 
Over. 

Every movement by the grain takes a single animation 
frame. A similar process is "stealing" a grain from the top 
chamber. This follows a similar path upwards, but walks the 
whole path at once each time it needs a new grain — see the 
comments below on the stealGrain function. 


The sample driver program 

This main program isn't a shining example of Macintosh 
programming style. It's just meant to show all the functionality 
of the subroutines. 

Menu commands let you select from among the three types 
of cursors; control the speed; and quit. That's about it. 

The structure of the program is simple. The main loop calls 
the cursor animation routine at idle time, also calls SystemTask, 
and then does simple event handling — just enough to operate the 
menus. 

One thing to note while using the program is the flicker. On 
a Macintosh Plus or SE, the screen refresh is linked to the tick 
count. Even though the task is not implemented as a VBL task, 
the cursor update takes place near the beginning of a tick. This 
is apparent on the Plus or SE because the cursor flickers more 
when it's near the top of the screen. On a Mac II, where the 
monitor's refresh rate isn't sync'd with the ticker, the cursor 
flickers sporadically at any point on the screen. 

A feature I included in the original (ca. 1986) program was 
away to measure how much CPU time the cursor animation takes 
up. The program would see how many times it could execute a 
loop with the cursor running at various speeds, and not running 
at all. I haven't done the measurements for this LightspeedC 
version, but that assembler version took up less than 2% of the 
CPU time if the animation was 15 times per second or less. 
Animating at 60 times per second could take up to around 7% of 
the time. You have to watch out for this, since your application 
is presumably showing the cursor to apologize for some slow 
operation in the first place! 
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[A side note: the time used is dependent on the cursor's 
horizontal position, since SetCursor has to shift the image into 
position — the function is a sawtooth curve with a 16-pixel 
period on a Mac Plus or SE. This took a long time to find...] 

Finally, note that “main.c” includes “AnimCurs.h”, which 
contains the prototypes specifying the interface to the package. 


The subroutines 

Here's a quick tour through the contents of the subroutine 
package. 

Data structures: Each of the three cursor variants has a struct 
defined for it, remembering the state of the drawing so it can be 
updated. Then there's a type “cursInfo”, which is a union of all 
three, plus the current cursor, timing information, and the vari- 
able controlling which type of cursor is being shown. 

Note that this structure has to remember the whole state of 
the cursor. For the watches, it just has to remember one or two 
hand positions. For the hourglass, it must keep track of whether 
or not there's a falling grain of sand, and the current column 
(stored asa bit) and row the sand is at. Unlike with the other types, 
the cursor data itself is part of the information, because some 
routines examine its bits to see where the sand should fall. 

Data: I've included all the masks and data in-line. They 
probably ought to be resources. If they were, some care would 
be needed if the routines were being called from a VBL task. 

Functions: 

The three initialization (acStartxxx) routines all do about the 
same thing: set up the delay, the type, the cursor mask and data, 
and type-specific information. 

Two utility routines (copy16, or16) are used to copy and 
combine the “Bits16” type, which holds a cursor's mask or data. 

hideGrain and showGrain just change the visibility of the 
current grain of sand. They're a good example of how the state 
information is self-contained; they need no parameters. move- 
Grain just updates the position by hiding, moving, and showing 
the grain. 

coinFlip is kind of cool. I didn't want to use QuickDraw's 
random number generator. (In addition to needing AS, it can 
mess up an application's random sequence by stealing elements 
from it nondeterministically.) So I used a method which is 
simplified from the engine used in the "DissBits" subroutine. 
Although the random numbers used in that subroutine are poor, 
the random bits used by coinFlip() are quite random. [See Knuth 
in Further Reading for details.] 

stealGrain takes a random pixel from the top chamber and 
turns it white. It works by percolating through black pixels until 
itreaches the top or runs out of black pixels. It’s a lot like the way 
a single black pixel percolates down through white ones, but it 
percolates all at once when a new grain is needed. dropGrain just 
steals a grain from the top, then sets up a new grain and marks it 
as moving. 

Three routines advance specific cursor types. nextWatch 
and nextWatch2 are very simple. nextHour drops a grain if 
needed and then advances the current grain by one pixel. doN- 
extFrame just cases out on the current cursor type to call one of 
these three. 
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Two final routines are called from the application: acNext 
should be called as often as possible. When it's time to do so, it 
computes and displays the next cursor. acDelay can be called to 
set the delay, in ticks, between frames. 


Projects for a rainy day 

I’ve kept the scope of this project small. Here are some 
varied ways you could take it from here: 

° Intercept GetResource calls for type ACUR and CURS in 
someone else’s application. When they think they’re just dis- 
playing a sequence of cursors, you could be computing and 
displaying something much more complex, such as the hour- 
glass. 

° Sort of the opposite: Intercept SetCursor calls and record 
the cursors and the delays in between them. Automatically build 
and save an ACUR resource. Then anything drawn “on the fly” 
(like the hourglass) can be transcribed as an ACUR and stored for 
simple programs (like the Finder) to use. Of course, these may 
turn out quite large. 

e Experiment with changing the mask in the hourglass so the 
glass part is “transparent”. You'll have to modify the mask as the 
data portion is modified, too. 

° Add an arrow type to the set of cursors supported, so 
acNext () can always be called at idle, whether or not there's 
animation going on. Hint: if the cursor variant is an arrow, 
acNext () does nothing. 

* Handle color cursors. 

° Time the routines and choose an optimal animation rate to 
keep the animation smooth yet lessen flicker and not use too 
much CPU time. Try it on various CPUs and monitors to check 
both performance and appearance. 

° Write a VBL task which makes the cursor animate auto- 
matically. Have it notice when another part of the program does 
a SetCursor trap, and assume this means it should turn itself off. 
(In an older program, I examined the low-memory cursor data to 
see if the cursor had changed; probably a bad move for color 
cursors...) 

° Put everything into a driver, so any development system 
can use it. Could you have it get time during SystemTask calls, 
so the application needn’t call it? 


Further reading 

For more on the method used in the coinFlip() routine, see: 

* Donald Knuth, The Art of Computer Programming, 2nd 
ed., Vol II: Seminumerical Algorithms,pp. 29-31 

* Mike Morton, "A Digital Dissolve Effect for Bitmapped 
Graphics Screens", Dr. Dobb's Journal , November 1986 

* Mike Morton, "The DissBits Subroutine", MacTutor, 
December 1985 

* William H. Press, et al, Numerical Recipes: The Art of 
Scientific Computation, pp. 209-213 


Knuth's writeup is the most interesting as far as a theoretical 


basis. The Recipes includes a useful table of constants. My DDJ 
article is more in-depth as far as applying the method. 
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For more on the vertical retrace manager, see: 

• “The Vertical Retrace Manager", Inside Macintosh, Vol. 
II, pp. 347-354 

* Robert B. Denny, "Using the Vertical Retrace Manager", 
August 1985 


For more on animation (of cursors or anything), 
See: 

* Dick Chandler, *VBL Task Animation", MacTutor, Feb- 
ruary 1989 

е Stuart Gordon, dir., *Re-Animator", 1985 

* Letters, MacTutor, March 1988, p. 12 

* Mike Morton, "Alternate Video Screen Animation", 
MacTutor, June 1986 

° David Stoops, “Animated Cursors", Letters, MacTutor, 
December 1988, pp. 108-109 


Conclusions 

We've covered three ways to animate cursors — two simple 
ones based on resource-like data and one which does the drawing 
more "by hand". Doing the drawing directly into a cursor with 
bit manipulation is much faster than using QuickDraw to set and 
clear pixels. It's acceptable because the format of a monochrome 
cursor isn't about to change. 

The animation routines are decoupled from the issue of 
whether the animation should be invoked from an idle routine or 
from a timed task. Timed tasks bring the risk that a user gets no 
indication of when the application is hung up, along with various 
technical subtleties. If you do want to make a task animate your 
cursor, it might be a good idea to make the task also check for 
signs of life in the application. 


Listing: AniaCurs.h 


/*Prototypes for the animated cursor subroutines. 
See "AnimCurs.c^ for details on how to call these. 
*/ 


void acStartHG (int delau);/* set ир for hourglass cursor */ 
void acStartW1 (int delau);/* set up for one-handed watch */ 
void acStartW2 (int delau);/* set up for two-handed watch */ 
void acDelau Cint delay); /* set delay between frames */ 

void acNext (void); 


Listing: 


/* idle-time call: advance cursor */ 
AniaCurs.c 
/*Animated Cursor subroutines. 


Copyright € 1989 by Michael S. Morton, all rights reserved. 
Written February '89 for MacTutor. Feel free to use these or 
modify them so long as the original author and source are 
noted. 


Routines included are: 

0 acStartHG - set the cursor to be an hourglass 

O acStartWi, acStartW2 - set the cursor to be а 1- or 2- 
handed watch 

O acDelay - set the delay, in ticks, between animation 
steps 

O acNext - idle-time routine 
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То set up any of these cursors, call the acStart_—. routine, 


passing the delay you’d like between frames. Then call acNext 


during your idle routine. To change the delay, call acDelay. 


To get a different kind of cursor, stop calling acNext and use 


SetCursor to get it. 


*/ 

/*State information for three cursor types: */ 

typedef struct /* info on the HOURGLASS: */ 

( long coin; /* used in random number generator */ 
int grainRow; /* row number (@..15) of falling grain */ 
int grainBit; /* bit mask for falling grain */ 
Boolean grainMoving;/* flag: is the grain still moving? */ 

) hourlnfo; /* define this tupe */ 

tupedef struct /* info on ONE-HANDED WATCH: */ 

( int wFrame; /* which frame of animation are we on? */ 

) watchllInfo; /* define this tupe */ 

tupedef struct /* info on TWO-HANDED WATCH: */ 

( int mFrame; /* frame of minute hand */ 
int hFrame; /* frame of hour hand */ 

) watch2Info; /* define this type 


/*Generalized cursor type: */ 

typedef enum 

( hgType, wiType, w2Type ) cursType; /* selects one of 
above structs */ | 


typedef struct /* tracks any kind of cursor */ 

( Cursor curs; /* current cursor */ 
int delay; /* delay between frames (ticks) */ 
long nextFrame; /* time of next frame (ticks) */ 
cursType type; /* type of cursor */ | 
union /* depending on type of cursor: */ 
( hourInfo hg; /* O info on hourglass */: 


watchliInfo w1; /* O info on one-handed watch */ 

watch2Info w2; /* O info on two-handed watch */ 

u; /* give union an easu name */ 
) cursInfo, *ciPtr; 


/*cursor information is used globally all through file. */ 
cursInfo theInfo; ^ /* sole instance of this struct */ 


/*16x16 data and masks for cursors. Some of these are OR'd 
together to make the two-handed watch. Others are just 
backgrounds which are drawn on, such as for the hourglass. */ 
int hourData [16] =  /* hourglass, about to start falling */ 
( OxFFFE, Ox7FFC, Ox7FFC, Ox7FFC, Øx5FF4, 0х4ҒЕ4, 0х47С4, | 
0x4384, 0х4284, 0х46С4, 0х4С64, 0х5834, 0х101С, 0х600С, 
0х4004, OxFFFE ); 
int hourMask [16] = ( ØxFFFE, OxTFFC, Ox7FFC, Ox7FFC, 0х5ҒҒ4, 
0х4ҒЕ4, 0х47С4, 0х4384, 0x4384, 0х41С4, 0х4ҒЕ4, 0х5ҒҒ4, 
0ХТЕЕС, @x7FFC, Ox7FFC, OxFFFE ); 


int watchMask [16] = (0x3E00, 0х3Е00, 0x3E00, 0х3Е00, OxTFOQ, 
0ХҒҒ8й, ÜxFF80, OxFFCO, OxFFCO, 0хҒҒ80, 0x7F00, 0х3Е00, 
Ox3EQ0, 0х3Е00, 0x3E00, 0х0000 ); 


int watchMinutes [12][16] = /* twelve minute-hand positions */ 


( 0х3Е00, 0х3Е00, 0x3E00, 0х3Е00, 0х4900, 0х8880, 0х8880, 
0х88С0, 0х80С0, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4300, 0х8480, 0х8480, 
0х88С0, 0х80С0, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0x3E00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8180, 0х8680, 
0х88С0, 0х80С0, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0x3F00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
Ox8FCO, 0х80С0, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
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0x88C0, 0x86C0, 0x8180, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
0х88С0, 0х84С0, 0x8480, 0x4300, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
0x88C0, 0х88С0, 0х8880, 0x4900, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0x8080, 
0х88С0, 0х90С0, 0x9080, 0х6100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0x4100, 0х8080, 0х8080, 
0х88С0, 0х80С0, 0хС080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
0ХҒ8С0, 0х80С0, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0хС080, 0х8080, 
0x88C0, 0х80С0, 0х8080, 0x4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х6100, 0х9080, 0x9080, 
0х88С0, 0х80С0, 0x8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ) 


int watchHours [8][16] = /* eight hour-hand positions */ 
( 


( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8880, 0х8880, 
0х8880,0х8080, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 
0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8480, 
е 0x8080, 0х4100, 0x3E00, 0х3Е00, 0х3Е00, 0х3Е00, 
0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
0х8Е80,0х8080, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 
0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
0х8880, 0х8480, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
0x8880, 0х8880, 0х8880, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
0х8880, 0х9080, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0x3E00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х8080, 
0х8880, 0х8080, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
0х3Е00, 0х0000 ), 

( 0х3Е00, 0х3Е00, 0х3Е00, 0х3Е00, 0х4100, 0х8080, 0х9080, 
0х8880, 0х8080, 0х8080, 0х4100, 0х3Е00, 0х3Е00, 0х3Е00, 
бзш, 0х0000 ) 


/*Function prototypes for stuff we define externally: */ 
*include "AnimCurs.h"^ 


/*Function prototypes for our static stuff: */ 

void acStartW CcursType type, int delay); /* start either kind 
of watch */ 

void copyl6 (int *src, Bits16 *dst);/* copy 16x16 bit image */ 
void or 16 Cint *src, Bits16 *dst); /* OR a 16x16 bit image */ 
void hideGrain (void);  /* hide current grain in hourglass */ 
void showGrain (void); /* show current grain in hourglass */ 
Boolean coinFlip (void); /* produce a pseudo-random boolean */ 
void stealGrain (void); /* remove a grain from top section */ 
void dropGrain (void); /* get a grain moving */ 

void moveGrain Cint dh, int dv);/* move a grain in transit */ 
void nextHour (void); /* compute next cursor: hourglass */ 
void nextWatch (void);  /* watch */ 

void nextWatch2 (void); /* 2-handed watch */ 

void doNextFrame (void); /* compute next frame and show it */ 


/*acStartHG () - Initialize the hourglass cursor, with the 
specified delay between animation frames. This is an external 
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routine. */ 
void acStartHG (delau) 
int delau; /* INPUT: pause between frames */ 
( thelnfo.delau = delay; /* record delay in structure */ 
theInfo.nextFrame = TickCount €) + delay; /* figure when to 
animate next */ 
theInfo.type = hgType; /* remember the type: hourglass */ 
theInfo.u.hg.grainRow = -1; /* make a grain drop in 
dropGrain () */ 


/*Initialize cursor data, mask and hotspot (altho dropGrain 
does data, too) */ 

сору16 ChourData, & CtheInfo.curs.data)); 

сору16 ChourMask, & CtheInfo.curs.mask)); 

theInfo.curs.hotSpot.v = 8; /* stick hotspot.. */ 

theInfo.curs.hotSpot.h = 8; /* „in middle */ 


дгорбгаіп ОО; /* start first grain dropping */ 
) /* end of acStartHG () */ 


/*acStartW1 ©) - Just like acStartHG, but with a one-handed 

watch. This is an external routine. 

*/ 

void acStartW1 (delay) 
int delay; /* INPUT: pause between frames */ 

( acStartW CwiType, delay); 

) /* end of acStartW1 () */ 


/*acStertW2 ©) - Just like acStartHG, but with a two-handed 

watch. This is an external routine. 

51 

void acStartW2 (delay) 
int delay; /* INPUT: pause between frames */ 

( acStartW (w2Tgpe, delay); 

) /* end of acStartW2 (С) */ 


/*acStartW С) - Start а one- or two-handed watch. */ 
Static void acStartW (type, delay) 
cursType type; /* INPUT: wiType or w2Type */ 
int delay; /* INPUT: pause between frames */ 
( theInfo.delay = delay; /* record delay in structure */ 
theInfo.nextFrame = TickCount С) + delay; /* figure when to 
animate next */ 
theInfo.type = type; /* remember the type */ 
if (буре == wiType) 
theInfo.u.w1.wFrame 
else 
( theInfo.u.w2.mFrame 
theInfo.u.w2.hFrame 


/* init different types: */ 
0; /* one-handed: set to zero */ 


= 0; /* two-handed: set minute */ 

= 0; ) /* „апа hour frame to zero */ 
/* Initialize the cursor data, mask and hotspot: */ 
сору16 (watchMinutes [Ø], & CtheInfo.curs.data)); 
сору 16 CwatchMask, & CtheInfo.curs.mask)); 
theInfo.curs.hotSpot.v = 8; /* stick hotspot.. */ 
theInfo.curs.hotSpot.h = 8; /* „їп middle */ 

) /* end of acStartW () */ 


/*copy16 С) - Сору an array of 16 ints into a Bits16 structure 
(the data or mask of a cursor. */ 
void сору16 (src, bits) 
register int *src; /* INPUT: source data */ 
811516 *bits; /* OUTPUT: where to stuff it */ 
( register int *dst = Cint *) bits;  /* coerce to a handier 
data type */ 
int i; /* FORTRAN- ish loop counter */ 
for (i = 0; i <= 15; із) *dst** = *src**; /* copy 16 words 
¥/ 
) /* end of copul6 () */ 


/*or 16 С) - Just like сору16 О, but we OR, not COPY. */ 
void or16 (src, bits) 
register int *src; 


/* INPUT: source data */ 


104 


Bits16 *bits; /* OUTPUT: where to stuff it */ 

( register int *dst = Cint *) bits; /* coerce to a handier 
data tupe */ 
int i; /* FORTRAN-ish loop counter */ 
for (i = 0; i <= 15; i++) *dst++ |= *src++; /* OR l6words */ 

/* end of or16 () */ 


/*hideGrain €) - Hide pixel where the current grain is. */ 
static void hideGrain () 

( theInfo.curs.data [theInfo.u.hg.greinRow] &= 

(~ theInfo.u.hg.grainBit); 


/*showGrain €) — Show the pixel where current grain is. */ 

static void showGrain () 

( theInfo.curs.data [theInfo.u.hg.grainRow] |= 
theInfo.u.hg.grainBit; 


/*coinFlip €) - Return a pseudo-random boolean value. We use 
shift-register system detailed in Knuth, among other places. 
x 


static Boolean coinFlip () 
( register Boolean result; 


if С! theInfo.u.hg.coin) /* zero? */ 
theInfo.u.hg.coin = 1; /* avoid demon state */ 
result = CtheInfo.u.hg.coin < 02;/* note if high bit set */ 


theInfo.u.hg.coin <<= 1; /* shift old value over 1 bit.. */ 
if (result) /* „and if top bit was '1'.. */ 
theInfo.u.hg.coin “= @xc5; /* .then futz with low bits */ 


return (result); 
) /* end of coinFlip () */ 


/*stealGrain - Grab a grain of sand from the top chamber of 
the hourglass. We want to percolate a white pixel up from the 
starting bit position. */ 

static void stealGrain () 

( register int v = 6; /* start at row 6, tip of top half */ 
register int hBit = 0x0100; /* start at the middle */ 
register Boolean done = false; /* haven't finished percolat- 

ing yet */ 
register int aboveWord; /* row of sand grains above us */ 
register Boolean leftOK, rightOK; /* are there bits to 

Steal above? */ 


while (! done) 
( ~; /* assume we can move up a row */ 
aboveWord = theInfo.curs.data [v]; /* get that row from 
the cursor image */ 


/*Decide which direction to steal from - if there's a 
grain right above us, we'll take that. Otherwise, we have to 
choose between the ones diagonally up from us. */ 

if CCaboveWord & hBit) == 0) /* have a bit above us? */ 

( leftOK = (0 != CaboveWord & (hBit << 1025; /* have 
Someone above on left? */ 

rightOK = (Ø != CaboveWord & ChBit >> 12220; /* someone 
above on right? */ 


/*Branch, depending on which way(s) we can go: */ 

if CleftOK && rightOK) /* both available? */ 

(АҒ CcoinFlip OD hBit <<= 1; /* yes: flip a coin. */ 
else hBit ››= 1; /* .to decide */ 


) 
else if CleftOK) hBit «« 1;  /* just left: take it */ 
else if (rightOK) hBit »» 1;/* just right: take it */ 
else ( **v; done = true; ) /* neither: back down */ 

) /* end of no bit above us */ 


if (v <= 1) done = true; /* if we hit top row, we have to 
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stop */ 
) /* end of while-not-done */ 


thelnfo.curs.data [v] &= (~ hBit); /* snuff this bit */ 
/* end of stealGrain С) */ 


/*dropGrain ©) — Get next grain of sand to fall. The “moving” 
flag is false. We get one grain of sand from the top chamber. 
If the bottom chamber is filled, we reinit the cursor to a 
full top chamber. Either way, we flagthat a grain is moving, 
and draw it. 

*/ 

static void dropGrain () 

( stealGrain (); /* pull a grain from the top chamber */ 


/*If the pile in the bottom chamber has filled it, the most 
recent grain dropped didn't get veru far. */ 
if (thelnfo.u.hg.grainRow < 9) /* are we piled too high? */ 
сору16 (hourData, & (thelnfo.curs.data)); /* yes: 
redraw all */ 


thelnfo.u.hg.grainRow = 8; /* set row number of new grain */ 
thelnfo.u.hg.grainBit = 0x0100; /* set bit in row */ 
theInfo.u.hg.grainMoving = true; /* we’re cooking with gas 
now */ 
showGrain (2; /* show the grain */ 
/* end of dropGrain (С) */ 


/*moveGrain С) — Move the current grain by a given delta. 
Note that a positive “dh” is a right shift. */ 
static void moveGrain (dh, dv) 

int dh, dv; /* INPUT: amount to move by */ 
( hideGrain О; /* hide where it is now */ 


theInfo.u.hg.grainRow += dv; /* update vertical position */ 

if (dh > 0) /* update horizontal position */ 
theInfo.u.hg.grainBit >>= dh; 

else theInfo.u.hg.grainBit <<= -dh; 


showGrain ОО; /* show where it is now */ 
) /* end of moveGrain () */ 


/*nextHour С) - Advance the hourglass by one frame. */ 

static void nextHour (С) 

( register int v, hBit;/* coordinate and bit pos of grain */ 
register int nextWord; /* word of grains below us */ 
register Boolean leftOK, rightOK; /* flags for OK 

directions to fall */ 


if С! theInfo.u.hg.grainMoving) 
last time? */ 
агорбгаіп С); 


/* grain hit bottom 
/* yes: get a new one */ 


v = theInfo.u.hg.grainRow; /* grab position and bit just. */ 
hBit = theInfo.u.hg.grainBit; /* ..for easier typing 
& efficiency */ 


nextWord = theInfo.curs.data [v*1]; /* get word below this 
one */ 
if ((nextWord & hBit) == 0)/* slot below us free? */ 
( moveGrain (0, 1); /* yes: just move down one */ 
return; /* and that’s all we need */ 


leftOK = (Ø == CnextWord & ChBit << 12220; /* have nobody 
below on left? */ 

rightOK = (Ø == C(nextWord & ChBit >> 1222; /* nobody below 
on right? */ 


/*Branch, depending on which way(s) we can go: */ 
if (leftOK && rightOK) /* can fall left or right? */ 
(АҒ CcoinFlip О) /* yes: randomly choose: */ 
moveGrain (1, 1); /* О fall to the right */ 
else moveGrain (-1, 1); /* о fall to the left */ 
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) 
else if CleftOK) moveGrain (-1, D;  /* left only: do it */ 
else if CrightOK) moveGrain (1, 1); /* right only: do it */ 
else theInfo.u.hg.grainMoving = false; /* can’t move: stop; 
reset next time */ 
/* end of nextHour () */ 


/*nextWatch – Compute the next frame of one-handed watch 
animation. */ 
static void nextWatch () 
( ++ theInfo.u.w1.wFrame; /* bump frame ahead by 1 */ 
if CCtheInfo.u.wl.wFrame) >= 12)/* outside of range 0.11? */ 
theInfo.u.wl.wFrame = 0; /* ges: wrap around */ 


сору16 (watchMinutes [theInfo.u.w1.wFrame], 
& CtheInfo.curs.data2); 
/* end of nextWatch () */ 


/*nextWatch2 - Compute the next frame of two-handed watch 
animation. */ 
Static void nextWatch2 () 
( ++ theInfo.u.w2.mFrame; /* bump MINUTE frame ahead by 1 */ 
if CCtheInfo.u.w2.mFrame) >= 12)/* outside of range 0.11? */ 
theInfo.u.w2.mFrame = 0; /* yes: wrap around */ 


copy 16 CwatchMinutes [theInfo.u.w2.mFrame], 
& CtheInfo.curs.data)); 


if CtheInfo.u.w2.mFrame == Ø) /* MINUTE frame just hit 12 
o'clock? */ 
( ++ theInfo.u.w2.hFrame; 
by 1 */ 
if CCtheInfo.u.w2.hFrame) >= 8)/* outside of range 0..7? 


/* yes: bump HOUR frame ahead 


| 


thelnfo.u.w2.hFrame = Ø;  /* yes: wrap around */ 


/*Add hour-hand image into minute-hand. */ 
or16 (watchHours [theInfo.u.w2.hFrame], 
& (thelnfo.curs.data)); 
) /* end of nextWatch () */ 


/*doNextFrame - Compute next frame, dispatching on type of 
cursor. */ 
static void doNextFrame С) 
( switch CtheInfo. type) 
( case hgType: nextHour С); break; 
case wllupe: nextWatch (2; break; 
case w2Type: nextWatch2 (2; break; 
default: break; 
/* end of switch on cursor type */ 
) /* end of doNextFrame () */ 


/*acNext-Idle-time animation. 

void acNext () 

( if (TickCount (С) < theInfo.nextFrame) /* time to animate 

yet? */ 
return; 


This is an external routine.*/ 


/* nope: return */ 


theInfo.nextFrame = TickCount С) + theInfo.delay; /* reset 
wake-up call */ 

doNextFrame С); /* draw next frame internally */ 

SetCursor (& CtheInfo.curs)); /* and display it */ 

/* end of acNext С) */ 

/*acDelay - Set delay, in ticks, between frames. This is an 
external routine. 
57 
void acDelau (delau) 

int delau; 
( thelnfo.delau = delay; 

theInfo.nextFrame = TickCount С) + delay; /* figure when to 
animate next */ 


/* INPUT: new delay */ 


/* end of acDelay С) */ 
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Listing: main.c 
/*Animated Cursor demonstration main program. 


Copyright @ 1989 by Michael S. Morton, all rights reserved. 
Written February ’89 for MacTutor. 
*/ 


include “AnimCurs.h” /* define functions in package */ 
/*Internal prototupes: */ 
void main (void); 
void makeMenus (void); 
void doMenu (long result); 
int theDelay = 4;  /* delay between animation frames, tix */ 
enum /* items in our sole menu */ 
( mnWatch = 1, mnWatch2, mnHourG, mnUnusedi, 
mnFaster, mnSlower, mnTop, mnUnused2, mnQuit ); 


void main () 

( EventRecord evtRec; /% info from GetNextEvent С) */ 
int inWhat; /* from FindWindow С): where was click? */ 
WindowPtr  theWin; /* unused - just for FindWindow () */ 
long menuResult; /* from MenuKey (С) or MenuSelect С) */ 


/*Usual initializations: perhaps more than we need here. */ 
InitGraf (&thePort); /* initialize QuickDraw */ 

InitFonts (); /* init the Font Manager */ 
FlushEvents CeveryEvent, 8);/* ignore pending events */ 


InitWindows (); /* init the Window Manager */ 
InitMenus (); /* init the Menu Manager */ 

TEInit (); /* init TextEdit */ 

InitDialogs (0L); /* init Dialog Mgr; no restart proc */ 
InitCursor (); /* show standard arrow cursor */ 
mekeMenus (); /* set up one cheep little menu */ 


acStartW1 CtheDelay); /* initialize to а one-handed watch */ 


/*Main loop: at idle time, update the cursor. Check for 
menu commands via the mouse or keyboard. */ 

while (1) 

( acNext ОО; /* idle time: animate the cursor */ 


SystemTask (); /* can’t hurt, altho we don’t do DAs */ 


if (GetNextEvent CeveryEvent, & evtRec))/* try for an 
event */ 
( if CevtRec.what == mouseDown) /* click? */ 
( inWhat = FindWindow CevtRec.where, &theWin); /* look 
up where it hit */ 
if CinWhat == inMenuBar ) /* menu click? */ 
doMenu (MenuSelect(& CevtRec.where))); /* track & 


process menu hit */ 
else SysBeep (2); /* can’t handle clicks elsewhere */ 
/* end of handling mouseDown */ 


else if CevtRec.what = keyDown) /% keypress? */ 
doMenu (MenuKey((char) evtRec.message)); /* don’t 
require cmdKey */ 
) /* end of handling one event */ 


) /* end of infinite loop */ 
) /* end of main () */ 


/*Make menu in-line. 
driver.) */ 

void makeMenus () 

( MenuHandle theMenu; 


(Resources? This is just a demo 


/* our sole menu */ 


theMenu = NewMenu (1, %\pMenu”); 

AppendMenu (theMenu, ”\pWatch/W; Two-handed watch/2;Hour- 
gless/H; (-^); 

AppendMenu CtheMenu, “\pFaster/F;Slower/S;Top speed/T;(-^)2; 

AppendMenu CtheMenu, *\pQuit/Q;(-%); 

AppendMenu CtheMenu, “\pAnimated Cursor Demo;written in 
LightspeedC^); 

AppendMenu CtheMenu, “\pCopyright € 1989;Michael S. 
Morton;for MacTutor”); 

InsertMenu CtheMenu, 0); /* put it in the menu ber */ 

DrewMenuBar (С); /* show our handiwork */ 

/* end of makeMenus () */ 


void doMenu (result) 
long result; /* INPUT: result from MenuSelect/Key */ 
( int command = LoWord (result); /* extract item number */ 


Switch (command) 

( case mnWatch:  acStertW1 CtheDelay); break; 
case mnWatch2: acStertW2 CtheDelay); break; 
cese mnHourG:  acStartHG (theDelau); break; 


/*Note that we can't let the delay go down to zero for 
“Faster”. */ 

case mnFester: 
(theDelay2; break; 


if CtheDelay» 1) -theDelay; acDelay 


cese mnSlower: **theDelay; acDelau 
(theDelau); break; 
case mnTop: theDelay = 1; acDelay 


(theDelay2; break; 


case mnQuit: ExitToShell С); break; 


default: break; /* ignore unrecognized items */ 
/* end of switch on command */ 

HiliteMenu (0); т 
/* end of doMenu () */ So, 
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abC 


Window Structures 


Welcome to the second incarnation of the MacTutor intro 


Bob Gordon 
Minneapolis, MN 
Volume 5, Number 6 


is add some additional data structures on the end. This simply 


column. The column is called abC because of its introductory 
nature (the *abc's"), and it uses the C language (the “С”). What 
I propose to do is to continue in the spirit of the previous set of 
articles, but focus less on C and more on the Mac. 

I also will not attempt to present a complete program each 
time. Since an introduction by its very nature tends to be a bit 
repetitive, I found the last time that the same code would appear 
for months at a time. This took up a lot of space in the magazine, 
and made it difficult to focus on one issue as we were always 
Carrying around a large amount of other code just to make an 
application work. This means that the articles will tend to be 
shorter, which will likely make it more possible for me to get 
them done. 

One other point before we start. I found that one of the most 
useful things in writing for MacTutor is getting mail. Feel free to 
write; Comments are much appreciated; and include your phone 
number. 


Making a Window 

One of the first steps in a Mac application is putting a 
window on the screen, typically in response to a request from the 
user. This method developed here is done entirely in code (as 
opposed to using resources). This has some limits, but offers the 
ability to easily add some features to ease the maintenance of 
windows. 

There are two points: First a window consists of the window 
stuff and the application specific stuff. From the Mac’s point of 
view, the window stuff consists of only the frame and does not 
even include the scroll bars (if any). On the other hand the 
application probably does not want to be concerned with such 
things as the scroll bars, zoom boxes, sizing, et cetera. 

Second, it is good programming practice to separate the 
application specific code from the more generic user-interface 
code. This eases maintenance and debugging and modification. 
To this end I created a file, shell.c which handles many of the 
generic properties, helper files (e.g. windowhelp.c) to add the 
capabilities I wanted, and the file app.c, which actually contains 
the parts of the application. In the snippets of code that follow, 
you will notice an occasional call to a function like appxxx(). 
This is a call in the shell part of the program to the app.c file. It 
is here, after, for example, preparation has been made for updat- 
ing a window (appupdate() ), that the application must update the 
application portion. 


windowhelp.h 


The windowhelp functions work because the Window- 
Record defined in the ToolBox is a fixed length object. What Idid 
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makes the object a little longer, but all the toolbox window and 
QuickDraw functions will work correctly. The advantage of 
doing this is that I can now keep additional information, which I 
think should be attached to a window in a safe place where I can 
always find it, and the application parts of the code need to 
concern themselves with it. 

One might suggest that the WRefCon (a field in the Win- 
dowRecord specifically for the application's own use) field is the 
proper place for this. This is probably true, but so much of this 
stuff seemed to either be more part of the window than the 
application (scroll bars) or likely to be part of any application 
(knowing whether the contents had changed or not), that it 
seemed a Good Idea to put it all together in one place. In this way 
much of the Mac user interface is handled for us each time we 
start a project. I use the WRefCon field to store the reference to 
the applications information proper. 

Now, I make have no pretenses that this is the optimal way 
of doing things. In fact, I know there are additions and changes 
Iam going to make, but if we wait to get all that worked out, we'll 
never get this written. 


A few comments about the flelds: 

The first four are what I call window margins. I noticed that 
many applications place various graphic objects around the 
edges of the window. There are scroll bars to the bottom and right, 
rulers on the top and tools on the left. Whatever it is, it brings in 
the edge of the window as far where the application can write. 
The window margins are sizes, in pixels of the areas reserved by 
things around the edges. The application can change them (if the 
user asks to see the rulers, for example). 

The next field, cursrt, is the rectangle defined by the window 
and the margins. I called it cursrt because outside the rectangle 
the cursor is typically the 11 o'clock arrow, and inside the cursor 
is whatever the application would like. 

The zoomrt is the rectangle to hold the size to zoom to if the 
user clicks the zoom box. Frankly, I haven’t implemented zoom- 
ing yet. It may be that we'll want two rectangles for zooming: one 
to hold the maximum size and one to hold the small (user set) size. 

mouser is a code for the mouse cursor. I made ita char simply 
because I couldn’t imagine anyone wanting more than 255 
cursors and because the built-in cursors are numbered one 
through four. If you want to add acursor resource, simply start the 
numbers at five and everything will work fine. And if you want 
more cursors or want to use bigger numbers, make it a short. 

The changed field simply states whether or not the window 
contents have changed. 

The next field, ckind (contents kind) I used to indicate the 
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kind of window. Currently this is either text or a object drawing. 
Whether this will stay this way or not I don’t know. Currently I 
use this in the functions that handle update and activation events 
to determine what to do. 

The last field is a handle to the current TextEdit record. A 
window may have more than one. This is needed because when 
a window is activated, the blinking cursor needs to be placed in 
whichever edit record the user left it in. 

As you can see, much of this information falls somewhere 
between what is strictly application specific and what is part of 
the window. Much of it, however, the application either need not 
be concerned with or is needed for almost all applications. 

Following the WindowStruct definition are several groups 
of #defines. The most interesting of these are the WDOC/ 
WGROW/WZOOM. By using these when you define a window 
(simply add together the ones you want), you can specify whether 
you want a simple document window to have a grow box or a 
zoom box. You can also add in the codes for the vertical or 
horizontal scroll bars. 


/*windowhelp.h */ 
#include “TextEdit.h’” 


®ifndef WINDOWHELP_H 
"def ine WINDOWHELP_H 


/* window add-on structure */ 


"define WindowStruct struct w. struct 
WindowStruct 


WindowRecord wr; /* the original window record */ 


uchar mtop; /* margin indents */ 

uchar mieft; 

uchar mbottom; 

uchar mr ight; 

Rect cursrt; /* rectangle used for cursor control */ 
Rect zoomrt; /* rectangle for zoom operation */ 

char mouser ; /* mouse pointer id Ccursor shape) */ 
char changed; /*if window contents havebeen changed */ 
short ckind; /% kind of contents */ 

TEHandle  curtext; — /* handle current te rec for window */ 


4 


"define Woffset 18 
"define SBarWidth 15 


/* these definitions allow easy generation of the four square 
*cornered titled windows. The basic (simplest) window is the 
*WDOC CNoGrowDocProc). To this optionally add WGROW to add a 
*grow box and/or WZ00M to add a zoom box. 

х/ 

"define WDOC 4 

"gefine WGROW -4 

"define WZ00M 8 

define WVBAR 16 

"define WHBAR 32 


/* specify the content of the window */ 
define CDRAW 1 
define СТЕХТ 2 


/* Value in windowKind field of WindowRecord by WindowNew 

* if the window has a grow box. This is used by routines that 
* redraw the window to decide whether to draw the grow box 

* or not 
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х / 
#def ine HASGROW 9 


#endif 


WindowHelp.c 

WindowHelp.c consists mainly of two functions, Win- 
dowNew() and WindowClose(. 

WindowNew() opens a window after creating a Window- 
Struct as shown above (no check for memory yet). Note that it 
only gets four arguments. The title (which can be a null string in 
which case the window is named “Untitled”), a percentage (the 
window is opened as a certain percentage of the monitor size), the 
windowkind (WDOC/WGROW/WZOOM), and the content 
kind. 

A few other notes: The call to АррРаре() is a kludge. It is 
supposed to return the page size. Currently some numbers are just 
hard coded in AppPage(). The page size is needed for scrolling. 
Just put in sizes for an 8.5 by 11 piece of paper (in pixels) or 
whatever size page you want. The call to AppNew() is where the 
application does the initialization of its own data for a new 
window and places a reference to it (typically a handle) in the 
WRefCon. 

WindowClose() closes a window. After checking to see if 
the window is a desk accessory (and handling that), it calls 
AppClose() to allow the application to close its own structures. 
Thenis closes the window and frees the memory. It is in here that 
we would check to see if the window contents had changed (and 
had not been saved) and ask the user if we were to save the file. 


/* windowhelp.c 

* provides some routines to aid in opening and closing 
* windows 

*/ 


#include “abc.h” 
8include “Quickdraw.h” 
®include "EventMgr .h^ 
8include “WindowMgr .h^ 
8include “MenuMgr .h^ 
Binclude “windowhelp.h” 
8include “controlhelp.h” 
8include "cursorhelp.h^ 


short w.total = 0; /* counts total number of windows opened*/ 
short w.count = 60; 
/* counts number of windows actually open */ 


WindowNewCtitle,percentsz,windkind, contk ind) 
char *title; 
short percentsz; 
short windkind; 
short contkind; 


char *thetitle; 
Rect boundsrt; 
WindowRecord *w; 
WindowStruct *ws; 


short width; 
short depth; 
short lef tedge; 
short topedge; 
Rect pagesz; 
short һаѕ5сго11; 
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hasscroll = windkind & WVBAR + WHBAR; 
/* mask out scroll bar options */ 
windkind &- 8; 


if (title) 
thetitle = title; 
else 
thetitle = “Untitled”; 
SetRectC&boundsrt, screenBits.bounds. left + 4, 


screenBits.bounds.top + 24, 
screenBits.bounds.right - 4, 
screenBits.bounds.bottom - 42; 
width = boundsrt.right - boundsrt.left; 
depth = boundsrt.bottom - boundsrt.top; 
AdjustRectC&boundsrt, 
topedge = 30 + Woffset * w total, 
leftedge = 30 + Woffset * w total, 
(Сдеріһ * percentsz) / 100) - topedge, 
((width * percentsz) / 100) - leftedge); 
ws = (WindowStruct *ONewPtr(sizeof CWindowStruct)); 
w = (WindowRecord 
х )NewW indow(ws, &boundsrt, CtoPstr(thetitle), True, 
windkind, CWindowP tr )- 1, True, 8); 
ws = (WindowStruct *)w; 
е (windkind) 


case documentProc : 

case zoomDocProc : 
w-)windowKind = HASGROW; 
break; 


if Cw->windowKind == HASGROW) /% set window margins */ 


ws-?mright = ws->mbottom = SBarWidth; 

AppPage(&pagesz ); 

if Chasscroll == WHBAR) 
ScrollNew(w,0,0, pagesz .right, HORZ); 

if (hasscroll == WVBAR) 
ScrollNew(w,0,0, pagesz .bottom, VERT); 

DrawControls(w); 

DrawGrowIcon(w); 


else 
ws-?mright = ws->mbottom = 0; 
ws-?mtop = ws-mleft = 0; 
wS-?changed = FALSE; 
wS-?ckind = contkind; 
ws-)curtext = NIL; 
SetCursorRect(w); /* set cursor rect for cursor control */ 


AppNew(w); /* function to open application structure */ 
w_count++; 

w_total++; 

PtoCstr(thetitle); 


) 


/* WindowClose() 
*Closes the window passed to it. Assumes window was opened 
ж with WindowNew(). If window is a desk accessory, it will 
* be closed correctly. If it is an application window, prior 
ж to the window close there is а call to AppCloseC) (which 
* the application must supply) to allow any application 
* specific closing. 
*/ 
WindowClose(w) 
WindowRecord *w; 


WindowStruct *ws; 
short refnum; 


if (ws = CWindowStruct *)w) 
if CCrefnum = w->windowKind) < 0) 
CloseDeskAcc(refnum); 
else 


AppClose(w); /* close app storage, must do before */ 
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CloseWindow(w);  /* 
DisposPtr(w); 
W-count-; /* decrement the window count */ 
if (w_count == 0) 
/* if the number of windows on screen goes to */ 
w_total = 0; 
/* zero, set total to zero so next time we */ 
) /* open a window it will start at the original */ 
) /* window position */ 


/* AdjustRect 
* adjusts coordinates of a rectangle by four separate 
* amounts. adjustment is in Ctowards center) if amounts are 
* positive and out if amounts are negative); 
*/ 
AdjustRect(rec,t,1,b,r) 
Rect *rec; 
short t,l,b,r; /* values to adjust rectangle by */ 


CloseWindow */ 


rec top ігі; 
rec left += 1; 
rec bottom -= b; 
recright -= r; 


/* RtGlobalToLocal 
* Adjusts a rectangle to local coordinates 
*/ 
RtGlobalToLocal(rt) 
Rect *rt; 
Point *pt; 
pt = (Point *)rt; 


GlobalToLocal(pt); 
pt**; 


GlobalToLocal(pt); 


The last little piece of code illustrates how these functions 
are called from the shell program.dofile() is part of the code that 
responds to menus. 


dof ileCitem) 
short item; 


WindowRecord *w; 
switchCitem) 
( 


case iNew : WindowNewC^^, 40, WDOC* NGROW*WVBAR, CTEXT ); 


break; 
case iClose: WindowCloseCFrontWindowC 22; 
break; 
case iQuit : while (w = (WindowRecord *)FrontWindow() ) 


WindowC lose(w); 


ExitToShe11(); 
break; 


I hope this gives you some ideas on how to handle windows. 
Since it сап open as many windows as you want, there should be 
some check for memory limits. I also hope this is suitably 
introductory. Again, if you have any questions or comments, 
please write. 
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C Workshop 
Sub and Superscripting with TE 


SUPERSCRIPTING AND 
SUBSCRIPTING IN TE 

Robert McKenzie formerly of Mountain Lake Software, Inc. 
as the project manager of network, file, and multitasking pro- 
gramming tools for ClassKit™ , a C++ object-oriented applica- 
tion framework. His career experience of 15 years ranges from 
programming parallel processor mainframes to desktop com- 
puters. For the past two and one half years he has been program- 
ming on the Macintosh with emphasis at the network and driver 
level. 


Introduction 

This article describes how to encrypt a super/subscripting 
scheme into the data structures of the new Text Edit manager 
routines. Adding this scheme requires that one or two trap hooks 
be intercepted. This is also shown. 

It was good to see Apple take a quantum leap from the 
original TE manager to the new TE manager. But with all the 
capabilities now built into TE, including color support and style 
runs, it’s hard to understand why they left out super/subscripting. 

An application which finally provoked me to look for a way 
to add this functionality to TE was a test generation program for 
teachers called MAKETEST®. In particular, teachers who need 
to indicate power/base notation need super/subscripting, unless 
of course they were to be limited to some Fortran-like notation, 
such as: 


x^34yz-25 


Data Structures in TE 
The method I will describe depends on the new TE manager 
routines. These routines provide the run styles which are needed 
to keep the necessary style information on a character by charac- 
ter basis. Trying to manage character by character style informa- 
tion in the old TE manager routines would require a completely 
different approach. 


STElement: 
stCount: INTEGER; 
stHeight: INTEGER; 
stAscent: INTEGER; 
stFont: INTEGER; 
stFace: Style; 
stSize: INTEGER; 


stColor: RGBColor; 


The data structure of interest is called an STElement (V- 
262). A style element in TE is the collection of individual styles 
common to a sequence of characters in the TE text buffer. Any 
sequence of characters that share the same combination of styles, 
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whether the sequences are adjacent or not, share the same style 
element entry in the TE manager’s data structures. 

As the TE manager updates the screen it checks where one 
run ends and another begins. Each time the styles of a character 
sequence change, the grafport's font and text information are set 
to the combination of fonts and styles found in the style element 
entry for the new style run. 

The TE manager does not draw characters one at a time. 
Once it has set the grafport's text parameters to the information 
contained in the style run, it calls the QuickDraw routine 
"DrawText' to draw all the characters within the style run at one 
time. 

Now we have a couple of pieces of information gathered 
which begin to suggest an approach for supporting super/sub- 
scripting within TE: 

1) STElements is where style combinations are held. This is 
where we need to find a place to store the super/subscripting 
flags. 

2) TE always uses 'DrawText' for displaying one or many 
characters. This can be verified by using the trap intercept 
functionality of TMON. By trying to intercept various traps 
while forcing TE to output to the screen in all the ways it can, you 
can determine that only DrawText is used. 

3) The grafport must be set with all the correct font and style 
information if the characters are to be drawn correctly with 
DrawText. 

If weare going to use the style element structure to store the 
super/subscripting flags, we must find some unused bits within 
one of the fields: stCount, stHeight, stAscent, stFont, stFace, 
stSize, or stColor. Super/subscripting requires a 3 state represen- 
tation: super/sub/normal. Therefore, we need 2 bits which can 
represent up to 4 states. 

The stStyle field seems like a likely place to look, especially 
since itis the field used to represent the standard styles. However, 
being a 7-bit set type it only leaves 1 unused bit. Not enough. 

The stCount, stHeight, stAscent, and stSize fields contain 
numeric values used to compute character spacing for any given 
combination of styles. If we tried to encode super/subscripting in 
one of these fields it would alter the values computed in the 
character spacing calculations. The unpredictability of when one 
of these fields might be used makes these fields particularly 
messy to use. 

It might be possible to use the stColor field if we imposed 
some constraints on the color schemes that could be used. For 
example, if we used bits O and 1 within the stColor field, that 
would mean that the other entries in the color table would have 
to be organized such that if 0-2 were added to it we would still get 
the same color. Otherwise, for example, if a user was typing with 
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green characters and chose only super/subscripting from the 
menu, the super/subscripted character might come out as, say, 
red instead of green. Of course you’d have to be very familiar 
with the Color manager in order to create a color table to avoid 
this problem. (See the Color manager of Inside Mac-V for more 
information on the Color manager.) 

This leaves only the stFont field as a place for these super/ 
subscripting bits to live. To know if this is possible we have to 
know how the font number is used. The most important point is 
how the font number is used to look up the character character- 
istics of the various fonts. When QuickDraw is called to output 
text,as when DrawTextis called, it passes the font number to the 
Font manager to get the font description information. The font 
number is checked against fonts that are already loaded. If the 
font is loaded, a handle to the font description information is 
given back to QuickDraw for its use. If it isn't loaded, then the 
font number is given to the Resource manager and, again, a 
handle is returned to QuickDraw. Great. With this knowledge we 
now һауе a well defined event in which an attempt to use the field 
we have altered can be intercepted, the super/subscripting bits 
temporarily masked, and the normal TE character processing 
sequence can then go on. Of course using 2 bits within the stFont 
field also causes constraints on the range of usable font values. 
Without tabulating all the existing font numbers in the world this 
constraint seems quite reasonable. 


Choosing the Super/Subscripting Bits 

The fontnumber is a 16-bit integer which allows for approxi- 
mately 32K fonts. That’s a lot of fonts for people to choose from. 
Most of the fonts that I know of are assigned increasing values 
starting at 0 (0 is the systemfont), so obviously we don’t want to 
use any of the low ordered bits within the font field. It’s also the 
case that many programmers assign a field to be a negative value 
when its meaning is to be temporarily or permanently changed. 
Therefore, I chose not to use bit 15 either. The two best bits to use 
are bits 13 and 14 of the integer field. 


Superscripting flag 


Subscripting flag 


The corresponding value for each bit is: 
13: 8192 
14: 16384 
This means that no fonts with numbers between 8192 and 
16384 can be used if we reserve these bits for super/subscripting. 
Does anybody know of such fonts? (My knowledge of font 
number assignment is limited.) Of course, giving the user a 
choice of over 8K fonts to choose from is still plenty. 


Setting the Super/Subscripting Bits 
Setting the super/subscripting bits is done quite easily, and 
in a straightforward manner using the normal TE manager style 
setting function. An example is shown in the 'doEditing' func- 
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tion in the source listing given. 
First I defined some C constants which define the 3 states of 
super/subscripting: 


SUPER 0х4000 
SUB 0x2000 


REGULAR @0xI!FFF 


/* THE 14th BIT */ 
/* THE 13th BIT */ 


/* BITS 0 - 12 */ 


When the user chooses one of these states, the existing font 
information is retrieved by using the function: 


TEGetStule((**TEH).selStart-1, 
&Stul,klhgt,kascent,TEH) 


In each case the old super/subscripting information is 
cleared with the bitwise AND operator: 


Stul.tsFont &= REGULAR; 


In the case of normal scripting this is all that needs to be done 
before resetting the style. If super or subscripting is chosen, the 
appropriate bit is set with an OR operator: 


Styl.tsFont |= SUPER; 
or 
Styl.tsFont |= SUB; 


Then all that needs to be done is to set the new style: 


TESetStyleCdoFont, &Style, 1, ТЕН); 


Shifting characters up or down 

To make use of the bits that we just set we need to hook into 
the QuickDraw DrawText function. It is when this function is 
called that we will make our move and fool the TE manager into 
shifting the characters appropriately. Hooking into the DrawText 
trap will be explained in the next section. 

But once our intercept routine has been called what do we 
do? We make use of point 3 from the 'Data Structures in TE' 
section which states that the grafport is set correctly just before 
the text is about to be drawn. When set, the grafport's font field 
will contain the font value set in the Styl.tsFont field above 
including our super/subscripting bits. Therefore, the hook rou- 
tine can get the font value from the grafport, test it for having 
either the super/subscripting bit set, and adjust the grafport's pen 
location appropriately. (See Figure 2) The complete routine is 
then: 


DrawlextHook(...) 
( 


register int fnt,offset; 
GrafPtr gptr; 


GetPortC&gptr ); 
fnt = gptr txFont; 


offset = (Cfnt & SUPER) 


: ((fnt & SUB) 
? 3 
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: 0)); 


if (offset) 
( Move(0,offset); 
TextFont(fnt & REGULAR); 


DrawTextCtext,pos,cnt); 


if Coffset) 
(  Move(0,-offset); 
TextFont(fnt); 


) 


Notice the first TextFont call resets the grafport's font to the 
expected font by stripping the subscripting bits. The textis drawn 
and, if needed, the pen loc and grafport font is restored to the state 
previously set by the TE manager. 


Intercepting the DrawText/GetResource traps 

Setting up trap hooks requires knowledge of assembly and 
stack management, particularly when mixing languages like I 
have done in this project. My programming was done under 
MPW using assembly and the GreenHill C compiler. Trap 
intercepting is itself a topic of interest. Here I will explain the 
important points as related to super/subscripting. 

The DrawText hook is used to call our DrawTextHook 
function described above. The GetResource hook is used to keep 
QuickDraw from being confused by astrange font value found in 
a style run. The GetResource hook will be called as the TE 
manager tries to setup the grafport with the character attributes of 
a style run before it calls DrawText. Trying to setup the grafport 
with an unknown font number is the same well-defined event as 
described earlier. 

When GetDrawTrapInfo and GetResTrapInfo are called at 
application startup time they merely calculate trap information, 
such as the amount of data space the trap needs, its code size, and 
its beginning location. These values are used to set up the hook 
functions in the system heap as required. 

As seen in the assembly source listing, the data space 
definitions only force the assembler to output the correct code. 
Actual allocation of data space for the hook routine must be done 
by the SetupHook function. The actual trap code is between the 
TrapBeg and TrapEnd labels. This is the code copied down into 
the system heap. 

Neither of these trap hooks is reentrant. Therefore, a call- 
level variable, “СІ УІ’, must be maintained in order to keep track 
of how deeply any calls to these routines are nested. If the CLvl 
becomes greater than one, then it should do nothing except act 
like the standard trap. 

When the toolbox calls the DrawText trap, we have to take 
care of transforming the Pascal-oriented parameters on the stack 
to MPW-C parameters. The Pascal call to DrawText has the 
form: 


DrawText(textPtr, firstByte, byteCount); 


where: 
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textptr: is a 32-bit pointer 
firstByte: isa 16-bit integer 
byteCount: is a 16-bit integer 


And, of course, the parameters get pushed onto the stack 
from left to right which would leave the stack in the condition: 


Return Address: RRRR 4 bytes 


byteCount: BB 2 bytes 
firstB yte: FF 2bytes 
TextPtr: PPPP 4bytes 


low mem ... : RRRR : BBFF : РРРР : ... high mem 


A7 

When calling a C routine, integers must be treated as 32-bit 
integers. Therefore the DrawText hook has a little stack manage- 
ment to do. (See Figure 1) First it saves the return address of the 
original caller and adjusts the stack pointer. Then it temporarily 
copies the byteCount value into DO without altering the stack 
pointer. Then to transform the firstByte value to a 32-bit integer, 
itsimply zerosout the high order word of the stack. Now the stack 
contains only the firstByte and textPtr parameters. Next the 
byteCount value in DO is extended to be a 32-bit integer and its 
value is pushed back on the stack. 

1) SvRTS « RRRR 


... : BBFF : PPPP : ... high mem 


A7 


2) DO = xxBB 


... : BBFF : PPPP : ... high mem 
A7 

3) ... 2 00FF : РРРР : ... high mem 
A7 


4) DO = BBBB 


5) ... : BBBB : OOFF : PPPP : ... high mem 


A7 
Figure. 1 
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C parameters are pushed on the stack from right to left. 
Insteadof trying to correct the ordering problem on the stack,and 
unnecessarily wasting time, we can Just take advantage of this 
knowledge and declare our DrawTextHook with its parameters 
in the reverse order. Therefore the omitted parameters to 
DrawTextHook above would be: 


DrawTextHook(cnt,pos, text) 


int cnt; 
int pos; 
char *text; 


~ 


I was writing and finishing this article just as the latest tech 
notes from Apple were issued. Tech Note #207 describes addi- 
tional functionality added to the TE manager in System 6.0. The 
significant addition with respect to this article is the TEDraw- 
Hook. It provides exactly the same kind of functionality that was 
required when writing the hook routine to intercept DrawText. 
The TEDrawHook function is provided with the same parame- 
ters, plus some, that is needed by the DrawTextHook function. 
Therefore, the DrawTextHook could be used as the definition for 
this now supported TE hook. 

The essence of the GetResource hook is much simpler. The 
only thing we have to do here is to keep the Font manager from 
returning bogus font information when given an altered font 
number with our super/subscripting bits set. 

We know that the Font manager is trying to look up font 
description information when it calls GetResource with a re- 
source type of ‘FOND’. Therefore, any time GetResource is 
called with this type, and following our constraint that no fonts 
in the range 8192 to 16384 will be allowed, then all the GetRe- 
source hook has to do is mask out the 13th and 14th bit of the font 
number where it sits on the stack. (See Figure 2) Once these bits 
are cleared, then we just let the Resource manager continue to do 
its thing. 


Summary Remarks 

A scheme to add the functionality of super/subscripting was 
presented. However, there are many alterations that can be made 
to this scheme in order to refine the functionality into a more word 
processing-like functionality. For example super/subscripted 
characters in this basic scheme are printed in the same point size 
and with a fixed offset of 3 points. A more sophisticated approach 
would be to reduce the point size of shifted characters and allow 
the user to choose how many points to offset the shifted charac- 
ters. 

However, beware that if these extra capabilities are added, 
you will also have to handle having the correct font description 
resources loaded correctly and, perhaps, reposition the pen loc 
more carefully. Otherwise, character blurring may occur. 


Listing: DoMake 


make > MakeMiniEdit 
MakeMiniEdit 
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Application 


Current Font: 128 
Select Subscripting: 8192+128 = 8320 


TESetStyl(...FontNum = 8320...); 
TEInsert(..."hello"...); 


DrawTextHook 
Toolbox shift pen loc 


| |  FetMg — — —— | |  FetMg — — —— 


Ps 


Cotitosourcerlook 
clear bits: 13,14 
on the stack Description 
for font-5 
returned 


128 


Resource File 


Fonts Nums: 
10: font-1 
128:  font-5 


512:  font-n 


Figure 2 


Listing: MakeFile 


MiniEdit ff windows.c.od 
MiniEdit.c.o 
SuperSub.c.o 
TrepDefs.8.0 
TrepHook .с.о 

link -bf à 
windows.c.o д 
MiniEdit.c.o д 
SuperSub.c.o д 
TrapHook.c.o д 
TrapDefs.a.o Ó 
*(clibraries)cruntime.o^ д 


< Q» 
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“(clibraries)cinterface.o” 9 
*(libraries) interface.o^ ò 
-о MiniEdit 


windows.c.of windows.c à 
MiniEdit.h 
c -gwindows.c 


MiniEdit.c.o f MiniEdit.c ò 
MiniEdit.h д 
TrapHook .h 
c -gMiniEdit.c 


SuperSub.c.o f SuperSub.c à 
TrapHook .h 
c -gSuperSub.c 


TrapHook.c.o f TrapHook.c 9 
TrapHook .h 
с -g TrapHook.c 


TrapDefs.a.o f TrapDefs.a 
asm -case obj TrapDefs.a 


Listing: TrapDefs.a 


С RERERERERERA ERAS ELE A AREAS EK ALAA ARS EA AK AREA ALARA AR AAA ARE 


; TrapDefs.a 


; 
„ХКХА 


PRINT OFF 
INCLUDE ‘Traps .8’ 
INCLUDE ‘SysEqu.a’ 
PRINT ON, OBJ 


CODEREFS FORCEJT 


StackFrame RECORD (A6Link),DECR 
DetaSizePtr: 8.11 
TrepSizePtr: ds.1 1 
TrepAddrPtr: ds.1 1 


retaddr : 08.1 1 
A6L ink : ds.11 
Stacksize: EQU * 


GetDrawTrapInfo PROCEXPORT 


WITH StackFrame 
link a6, stacksize 


move.] DataSizePtr(a6),a8; compute size of parm's. 


lea — ParmEnd-ParmBeg,81; put it in а ‘с’ var 
move.1 а1, (ад) 

поме. 1 TrapSizePtr(a6),a0; compute size of trap 
lea  TrepEnd-TrepBeg,81; put it in а 'c' var 
поуе.1 а1, (ай) ; put hook address ... 

тоуе.1 TrapAddrPtr(a6), að 

lea TrepBeg,81 ; in а “с” variable. 

поуе.1 a1, Сад) 


unik аб 
rts 
ENDWITH 

ParmBeg 
SvRTS dc.18 ; place holder for compiling. 
FcAdr dc.10 ; place holder for compiling. 
TpAdr dc.10 ; place holder for compiling. 
CLv1 dc.18 ; place holder for compiling. 
ParmEnd 


; The following block of code actually gets copied down into 
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; the SysHeap due to trap table nearness requirements... 


TrapBeg lea CLv1,a0; keep track of nested hook calls. 
addq.w 81,(а0); see how many calls deep we are. 
cmpi.w 81.(а0) ; just call trap if call level > 1. 
bgt.s CallTrap 

CallHook lea | SvRTS,80 ; save address to get back too... 
тоуе.1 (a7)+, (að); save ‘len’ parm to ‘DrawText’ 
move.w (a7),dð ; ‘cir.w’ trans'offset^ to ‘int’ 
clr.w (a7) ; transform ‘len’ parm to MPW-C ‘int’. 
ext.) 00 ; put ‘len’ parm back on stack. 
move.] dð,-(a7) ; get out address of our trap. 
поуе.1 FcAdr,a@ ; call with MPW-C stack parms. 
jsr (a0) ; do a ‘pascal’ clean up. 
edd.| 812,87 
lea (Сіуі,а0; indicate exit of nested call. 
Subi.w #1, (ад) ; setup jump to original caller. 
move.1 SvRTS, ad ; get out of here!! 
jmp (að) 

Calllrap Леа CLvl,a0; indicate exit of nested call. 
subi.w #1, Сай) ; just call standard trap. 
поуе.1 TpAdr,aQ ; this won't come back here. 
jmp (að) 

TrapEnd 


ENDPROC 


GetResTrapInfo PROC EXPORT 


WITH StackFrame 
link a6,*stacksize 
поуе.1 DataSizePtr(a6),a8; compute size of parm’s. 
lea ParmEnd-ParmBeg,a1; put it in а 'c' var 
move.1 а1, (ад) 
томе. 1 TrapSizePtr(a6),a8; compute size of trap 
lea TrapEnd-TrapBeg,al; put it in a ‘с’ var 
поуе.1 ai, (ад) 
поуе.1 TrapAddrPtr(a6),a8; put hook address ... 
lea TrapBeg,al ; in a “с” variable. 
поуе.1 a1, (аб) 


unlk аб 
rts 
ENDWITH 

ParmBeg 
SvRTS dc.18 ; place holder for compiling. 
FcAdr dc.18 ; place holder for compiling. 
TpAdr дс.10 ; place holder for compiling. 
CLv1 dc.18 ; place holder for compiling. 


ParmEnd 
FontID EQU 4 


; The following block of code actually gets copied down into 
; the SysHeap due to trap table nearness requirements... 


TrepBeg lea CLvl,a@ ; keep track of nested hook calls. 
addi.w *1,Ca0) ; see how many calls deep we are. 
cmpi.w #1, Саб); just call trap if call level > 1. 
bgt.s CallTrap 

; unload the resType from the stack. 
поуе.1 6(а72,00 ; check it for type ‘FOND’. 
cmpi.] 8’FOND’,d@ ; do nothing if it isn't. 
bne.s CallTrap; else - clear special super/sub bits 
; so FontMgr gets Font info of a known Font. 
andi .w *$1FFF,FontIDCa?7) 


CallHook: 


CallTrep:lea CLvl,a0; indicate exit of nested call. 
subi .w #1, (аб) ; just call standard trap. 
тоуе.1 TpAdr,a2; this won't come back here. 
jmp (ad) 

TrapEnd 
ENDPROC 
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UnChainHookPROC EXPORT 

WITH StackFrame 
link a6,"stacksize 
поуе.1 TrapSizePtr(a6),a8; compute size of trap 
lea TrapEnd-NormTrap,a! ; put it in a 'c^ var 
move.) a1, (ад) 
поуе.1 ТгарАдагРігСаб), ай; put hook address ... 
lea NormTrap,al ; put it in a ‘с’ variable. 
move.1 a1, (ад) 
unlk a6 
rts 

ENDWITH 


SvRTS дс.10 ; place holder for compiling. 
FcAdr dc.10 ; place holder for compiling. 
TpAdr dc.18 ; place holder for compiling. 
CLv]1 dc.10 ; place holder for compiling. 
NormTrap ; just call standard trap. 
поуе.1 TpAdr,aQ ; this won't come back here. 
jmp (ad) 
TrapEnd 
ENDPROC 
END 


Listing: TrapHook.h 


/^ХЖЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


TrapHook .h 


EXOOCODOOIOOODOIOOEIOORCOIOOEOIOOEIOOROOROOEOIOOEOIOOIOOEOOOOOOIOOEOOOIOOOOIOOEOE / 


"define SUPER 0х4000 
"define SUB 0х2000 
"gef ine REGULAR Ox IFFF 


typedef 

struct TrapHookRecord 

( long SvRTS; 
long FuncAddress; 
long TrapAddress; 
Tong HookCallLevel; 
long Code; 

) TrepHookRecord, *TrapHookPointer; 


Listing: TrapHook.c 


/%*ЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖАЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


TrapHook .c 
HERERER AAA ARR AAA EERE KAKA ERE R AKA EERE KAKA AKER И 


8include “TrapHook .h” 
8include <Memory.h> 
8inciude <Menus.h> 
Binclude <strings.h> 


Bdef ine DrewCharNum 0х083 


extern long InsertHookAddr; 


SetupHookCInfoFunc,HookFunc, 
TrepNum, HookAddr , Normal Trap) 


int C*InfoFunc2C); 

long HookFunc; 

int TrapNum; 

TrapHookPointer *HookAddr; 
long *Normal Trap; 

int ParamsSize; 

int CodeSize; 


long CodeAddr; 
long OldZone; 
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(*InfoFunc )(&CodeAddr , &CodeSize, &ParamsSize); 


/* MAKE SURE TRAP HOOK IS IN SYS HEAP... */ 

OldZone = Clong)GetZone(); 

SetZone (SystemZone()); 

*HookAddr = CTrapHookPointer ) 
NewPtr(ParamsSize + CodeSize); 

SetZone (OldZone); 


*NormalTrap= GetTrapAddress(TrapNum); 
C**HookAddr ) .FuncAddress = HookFunc; 
C**HookAddr ). TrapAddress = *NormalTrap; 
(**HookAddr ) .HookCallLevel = Ø; 
BlockMoveCCodeAddr , &CC**HookAddr ). Code), CodeS ize); 


SetTrapAddress(&((**HookAddr ) . Code), TrapNum); 


UnsetTrapHookCHookAddr 2 
TrapHookPo inter HookAddr ; 


int CodeSize; 
long CodeAddr ; 


UnChainHook(&CodeAddr , &CodeS ize); 


BlockMove(CodeAddr , & CHookAddr-? Code) , CodeSize); 


Listing: windows.c 


ЖЖЖЖ 


Windows.c 
ЖЖЖЖ / 


/* NEEDED TO DEFINE NEW TEXTEDIT ROUTINES IN TEXTEDIT.H */ 
"def ine . ALLNU..— 


8include <QuickDraw.h> 
®include «Types.h» 
8include <Windows.h> 
*include «TextEdit.h» 
8include <Controls.h> 
include «Events.h» 
"include <fonts.h> 
8include «toolutils.h» 


8 include "MiniEdit.h"^ 


extern WindowRecord wRecord; 

extern WindowPtr myWindow; 
extern ControlHandlevScrol!; 

extern TEHandle TEH; 


extern char dirty; 
extern Str255 theF ileName; 
Ж AAA AA Aenean mmm naman anna nan mannannan naan mannan annnan x / 
coe 
Rect destRect, viewRect; 
Rect vScrollRect; 
Font Info nyInfo; 
int height; 
TextStyle Styl; 
muWindow = GetNewWindow(windowID,&wRecord, (WindowPtr)-1L); 
SetPort(muWindow); 
vScrollRect = (*myWindow).portRect; 


vScrollRect. left = vScrollRect.right- 15; 
vScrollRect.right += 1; 
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vScrollRect.bottom -= 14; 

vScrollRect.top -= 1; 

vScroll = NewControl(muWindow, &vScrollRect, 
“” 1, Ø, Ø, Ø, scrollBarProc, ØL); 


viewRect = qd.thePort->portRect; 
viewRect.right -= SBarWidth; 
viewRect.bottom -= SBarWidth; 
InsetRect(&viewRect, 4, 4); 


TEH = TEStylNewC &viewRect, &viewRect ); 
Styl.tsFont» newYork; 

Styl.tsSize2 14; 
TESetStyleCdoSize*doFont, &Styl, 1, TEH); 


SetViewCqd. thePort); 
dirty = 8; 


Co О) 
int oldScroll, newScroll, delta; 
oldScroll = C**TEH).viewRect.top - (**TEHD.destRect . top; 
newScroll = GetCtlValueCvScroll) * (**TEH).lineHeight; 
delta = oldScroll - newScroll; 


if (delta != 0) 
TEScrol1(0, delta, ТЕН); 


SetVScrollC) 
' register int n,lines; 
lines = linesInView(TEH,NULL); 
n = (**TEH).nLines-lines; 
if CCC**TEH).teLength > 0) && 
CC*CC*¥TEH) Text) (C**TEH). teLength- 1J==’\r’)) 


nt+; 


SetCtlMax(vScroll, n> 0 ? n : 0); 


oo 


register int topLine, bottomLine, theLine, lines; 


SetVScro11(); 
AdjustText(); 


lines = linesInViewCTEH,NULL ); 


topL ine = GetCtlValueCvScro112; 
bottomLine = topLine + lines; 


if CC**TEH).selStart < (**TEH). lineStarts[topL ine] || 
(**TEH).selStart >= 
(**TEH).lineStarts[bottomLine]) 


for (theLine = 0; 
(**7TEH).selStart >= (**TEH). lineStarts[theLine]; 
theL ine++) 


. 
4 


SetCtlValueCvScroll, theLine - lines / 2); 
AdjustText(); 
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linesInViewCTEHd1, above?) 
TEHandle — TEHd1; 
int *above; 


register LHHandle LHHd1; 

register LHPtr ^ LHptr; 

register int nLines,before,within; 
Rect dest,view; 


dest = (**TEHd1).destRect; 
view = (**7EHd1).viewRect; 


LHHd] = (¥*GetStylHandleCTEHd1)).1hTab; 
nLines = (**TEHd1).nLines; 
before = 0; 


HLockCLHHd12; 
LHptr = *LHHdl; 


while CCdest.top < 0) && (before < nLines)) 
dest.top += LHptr[before**]. lhHeight; 


within = before; 


while CCdest.top < view.bottom) && (within < nLines)) 
dest.top += LHptr[within*t*].lhHeight; 
HUnlockCLHHd1); 


if (above) *above = before; 
within -= before; 


return(within); 


SetViewCw) 
WindowPtr w; 


(**TEH).viewRect = w->portRect; 
(**TEH).viewRect.right-= SBarWidth; 
(**TEH).viewRect.bottom -= SBarWidth; 
InsetRect(&(**TEH).viewRect, 4, 4); 


(**TEH).destRect.right = (**TEH).viewRect.right; 
TECalTextCTEH); 


UpdateWindowCtheWindow) 
WindowPtr  theWindow; 


GrafPtr savePort; 


GetPort( &savePort ); 
SetPort( theWindow ); 


BeginUpdateC theWindow ); 
EraseRectC&theWindow-?portRect); 
DrewControlsC theWindow ); 
DrawGrowIcon( theWindow 2; 

TEUpdateC &theWindow-?portRect, ТЕН ); 

EndUpdate( theWindow 2; 


SetPortC savePort 2; 


pascal void ScrollProcCtheControl, theCode) 
ControlHandle theControl; 
int theCode; 
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int pageSize; 
int scrollAmt; 
int lines; 


if (theCode == 0) 
return; 


lines = linesInViewCTEH,NULL); 
pageSize = lines - 1; 

switch CtheCode) 

( 


case inUpButton: 
scrollAmt = -1; 
break; 

case inDownButton: 
scrollAmt = 1; 
break; 

case inPageUp: 
scrollAmt = -pageSize; 
break; 

case inPageDown: 
scrollAmt = pageSize; 
break; 


SetCtlValueC theControl, GetCtlValueCtheControl)*scrollAmt 
); 
AdjustText(); 


DoContentCtheWindow, theEvent) 
WindowPtr theWindow; 
EventRecord*theEvent ; 


int cnt 1Code; 
ControlHandle theContro! ; 
int pageSize; 
GrafPtr savePort; 


GetPortC&savePort); 
SetPortCtheWindow); 
GlobalToLocalC &theEvent- where ); 


if (CentlCode = FindControlC&theEvent-? where, 
í theWindow, &theControl)) == 0) 


if (PtInRect( &theEvent->where, &(**TEH).viewRect )) 
TEClick( &theEvent->where, 
CtheEvent->modifiers & shiftKey )!=0, 
TEH); 
) 
else 
( (cnt]Code == inThumb) 


TrackControl(theControl, &theEvent->where, ØL); 
AdjustText(); 


else 
TrackControl( theControl, 
&theEvent-»where, Scrol Proc); 


setPort(savePort); 


MyGrowWindow( w, p ) 
WindowPtr w; 
Point p; 


GrafPtr savePor t ; 
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long  theResult; 
int oScroll,b,r; 
Rect rct, oView; 


GetPort( &savePort ); 
SetPortC w ); 


b = qd.screenBits.bounds.bottom; 
r = qd. screenBits.bounds right; 
SetRect(&rct, 80, 80, r, b); 
theResult = GrowWindow( w, p, &rct ); 


if CtheResult == 0) 
return; 


SizeWindow( w, LoWord(theResult), HiWord(theResult), 1); 


InvalRect(&w-?portRect); 
oView = (**TEHD.viewRect; 
oScroll = GetCtlValue(vScro11); 


SetView(w); 
HidePen(C); 
MoveControlCvScroll, 
w->portRect.right - SBarWidth, w->portRect.top-1); 
SizeControl(vScroll, SBarWidth+1,w->portRect bottom - 
w->portRect. top-(SBarWidth-2)); 
ShowPen(); 


SetVScro11(€); 
AdjustText(); 


SetPort( savePort ); 


(oe 


HideWindowC myWindow ); 

TESetSelectC 0, (**TEH).teLength, ТЕН ); 
TEDeleteC ТЕН ); 

SetVScroll(); 


Listing: SuperSub.c 


/YFYKXXXXKXXXXXXXX1.1XXXXXXXXXXXX111XX1X2X1XX1XXFXXXXXX1XXXXXX1XXXXXX 


Super Sub. c 
POOOOOODCOOODPOOEEOOOOOOOEDOOOOOOOOOOOOOOOOODOOOOOOOOOEOORXE / 


8include <QuickDraw.h> 
include <Types.h> 

8* include «Fonts.h» 
include «Windows.h? 
8include «Menus.h? 

8* include «TextEdit.h» 
8include «Dialogs.h? 
include «Events.h» 
®include «Desk.h» 
"include <Files.h> 

*Üf include «ToolUtils.h» 
8include «Controls.h? 
"include <strings.h> 


8include “traphook .h” 


extern TEHandle TEH; 


р аны ыы ы ша ыда ыны адын ины ыда ыы жамалы A x/ 
DrawlextHook(cnt, pos, text) 

int cnt; 

int ров; 
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char  *text; 


register int fnt,offset; 
GrafPtr gptr; 


GetPort(&gptr >; 
fnt = gptr-> txFont; 


offset = ((fnt & SUPER) ? -3 : ((fnt & SUB) 2 3 : 9)); 
if Coffset) 


Listing: MiniEdit.c 


/¥ERERERARAEAAEA AERA AE AER ERA AAEAER AKER ER EEA EA ELAR ALA EAE LE 


MiniEdit.c 


2:32522441449412333333552252225222222222222222222222222 224) 


/* NEEDED TO DEFINE NEW TEXTEDIT ROUTINES IN TEXTEDIT.H */ 


define —ALLNU__ 


? include «QuickDraw.h? 


( Move(CO, offset); 
TextFontCfnt & REGULAR); 

DrawTextCtext,pos,cnt2; 

if (offset) 


( Move(0,-offset); 
TextFontCfnt); 


Listing: MiniEdit.h 


/YX53345353535355X55X5X5XX5X5X5X355XXXXXXXXXXXXXXXX5X2XXXX5XXX 


MiniEdit.h 


XXXXX1XXXXXXXX1XXXXXXX1XX1XXXXXX75XXXXXXXXXXXXXXXXXXF4XKXXXXXXX / 


def ine windowID 128 
gef ine ErrorAlert 256 
"define AdviseAlert 257 


/* resource IDs of menus */ 
“define appleID 128 
"define fileID 129 
"define editID 130 


/* Edit menu command indices */ 
def ine cutCommand 1 
"define copyCommand 2 
"define pasteCommand 3 
define TimesCommand 5 

def ine GenevaCommand 6 

def ine NewYorkCommand 7 
define s9Command 9 

"def ine s10Command 10 
def ine s 12Command 11 
def ine s14Command 12 
def ine s18Command 13 
define plainCommand 15 
"define ulineCommand 16 
define boldCommand 17 
8def ine italicCommand 18 
"define shadowCommand 19 
"define | SuperCommand 20 
def ine RegularCommand21 
def ine SubCommand 22 


include 
include 
# include 
tt include 


«Types. h? 
«Fonts.h? 


«Windows .h? 


«Menus .h? 


*include «TextEdit.h? 
*include <Dialogs.h> 
include <Events.h 
include «Desk.h? 
"include <Files.h> 
include «ToolUtils.h» 
include «Controls.h? 
include «resources.h? 
8$include «strings.h? 
*include «Scrap.h? 


"include "MiniEdit.h^ 
include “TrapHook .h^ 


"Üüdef ine DrawCharNum2x085 
define GetRes Ox 1A9 


WindowRecord wRecord; 
WindowPtr nyWindow; 
TEHandle TEH; 

Rect dragRect - ( 0, 0, 1024, 1024 ); 
MenuHandle nyMenus (31; 
ControlHandle vScroll; 
Cursor editCursor; 
Cursor waitCursor; 
char dirty; 
EventRecord nyEvent; 

int baseoffset = 0; 


TrapHookPointer ^ InsertHookAddr; 


TrapHookPointer ^ ResHook; 


long NormalTrap; 

long ResTrep; 

GetDrawTrapInfoC); 

GetResTrapInfo(); 

DrawTextHook(); 

/* аласа sin ne eee ee ее SSE ANA е ие ее Am ее ае е бча ef */ 
mainc) 


int  muRsrc; 


InitGraf (&kqd.thePort); 
InitFonts(); 


FlushEvents( everuEvent, 0 ); 


/* Menu indices */ 
"def ine appleM g 
"def ine f ileM 1 
define editM 2 
define fmQuit 1 
define aaSave 1 
def ine aaDiscard 
"def ine aaCancel 3 
define SBarWidth 15 
def ine NULL ØL 
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InitWindows(); 
InitMenus(); 
TEInit(); 


InitDialogs(@L); 


InitCursor(); 
MaxApp1Zone(); 


SetUpCursors(); 
SetUpMenus( ); 
SetUpW indowsC); 


SetupHook(GetDrawTrapInfo,DrawTextHook, 
DrawCharNum, & Inser tHookAddr , &NormalTrap?; 
SetupHookCGetResTrapInfo, NULL, 
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GetRes, &ResHook, &ResTrap); 
while (MainEvent()); 


UnsetTrapHook( Inser tHookAddr ); 
Unset TrapHook СВеѕНоок ) ; 


doMouse(myEvent ) 
EventRecord*myEvent; 


WindowPtr whichWindow; 


е (FindWindow( &myEvent->where, &whichWindow )) 


case inDesk: 
break; 
case inGoAway: 
if (ours(whichWindow)) 
if (TrackGoAwau( muWindow, 
myEvent->where) ) 
/*DoFile(fmClose) */ 


break; 
case inMenuBar: 
return( DoCommand( 
Menuse lect(myEvent->where) ) ); 
case inSusWindow: 
SustemClick( &myEvent, whichWindow ); 
break; 
case inDrag: 
if CoursCwhichWindow)) 
DragWindow( whichWindow, 
&myEvent->where, &dragRect ); 
break; 
case inGrow: 
if CoursCwhichWindow)) 
MuGrowWindow( whichWindow, 
&myEvent->where ); 
break; 
case inContent: 
if CwhichWindow != FrontWindow()) 
SelectWindow(whichWindow); 
else 
if (ours(whichWindow)) 
DoContent(whichWindow, &muEvent); 
break; 
) default: ; 


return(1); 


doKeu(muEvent) 
EventRecord *muEvent; 
register char theChar; 


theChar = myEvent-?message & charCodeMask; 
if C((ngEvent- modif iers & cmdKey) != 0) 

return( DoCommandC MenuKeyC theChar ) 2); 
else 


TEKeyC theChar, ТЕН 2; 
ShowSelect(C); 
dirty = 1; 


return( 1); 
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doActivateCmyEvent) 
EventRecord *myEvent; 


Rect rct; 


( Cours(CWindowP tr myEvent-> message )) 


rct = (*myWindow).portRect; 

rct.top = rct.bottom - (SBarWidth*1); 
rct.left = rct. left - (SBarWidth*1); 
InvalRect(&rct); 


if С myEvent->modifiers & activeFlag ) 


TEActivate( ТЕН ); 
ShowControlC vScroll ); 
TEFromScrap(); 


else 


TEDeact ivate(TEH); 
HideControlC vScroll ); 
ZeroScrap(); 
TEToScrap(); 


) 


return(1); 


int MainEvent() 
( 


WindowPtr whichWindow; 
MaintainCursor(); 
MaintainMenusO; 


SetTrapAddress(NormalTrap, DrawCharNum); 
SetTrapAddress(ResTrap,GetRes); 


SystemTask(); 


SetTrapAddress(&( Inser tHookAddr->Code), 
DrawCharNum); 
Set TrapAddress(&(ResHook-> Code), GetRes); 


TEIdleCTEH); 
N (GetNextEvent(everuEvent, &muEvent)) 


switch (muEvent.what) 

( case mouseDown: 
return(doMouse(&muEvent)); 
break; 

case keuDown: 

case autoKey: 
returnCdoKeyC&myEvent )); 
break; 

cese activateEvt: 
returnCdoAct ivateC&myEvent)); 
break; 

case updateEvt: 
if CoursCC(WindowPtrOmyEvent . message?) 

UpdateWindow(myWindow); 

break; 

default: ; 


) 


return(1); 


Se tUpMenusC С) 
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int i; 


muMenus[appleM] = NewMenu( appleID, 
AddResMenu( myMenus[appleM], ‘DRVR’ ); 


muMenus[fileM] = GetMenu(fileID); 
muMenus[editM] = GetMenu(editID); 


for С (ї=арр1еМ), Ci<=editM); i++ ) InsertMenuCmyMenusl i 1, 


0) ; 


DrawMenuBar( 2; 


doEditingCtheItem) 
int theItem; 


WindowPeek wPtr; 
TextStyle Styl; 
int lhgt,escent; 


wPtr = (WindowPeek) FrontWindowC); 


Switch CtheItem) 

( case cutCommand: 
TECutC TEH ); 
dirty = 1; 
break; 

case copyCommand: 
TECopyC ТЕН 2; 
break; 

case pasteCommand: 
TEPasteC TEH ); 
dirty = 1; 
break; 


case TimesCommand: 
Styl.tsFont = times; 


TESetStyleCdoFont, &Styl, 1, ТЕН); 


break; 
case GenevaCommand: 
Styl.tsFont = geneva; 


TESetStyleCdoFont, &Styl, 1, ТЕН); 


break; 
cese NewYorkCommand: 
Styl.tsFont = newYork; 


TESetStyleCdoFont, &Sty1, 1, ТЕН); 


break; 


case s9Command: 
Styl.tsSize = 9; 


TESetStyle(doSize, &Styl, 1, TEH); 


break; 
case s 18Command: 
Styl.tsSize = 10; 


TESetStyle(doSize, &Styl, 1, TEH); 


break; 
case s 12Command: 
Styl.tsSize = 12; 


TESetStyleCdoSize,&Styl, 1, TEH); 


break; 
case 5 14Соттага: 
Stul.tsSize = 18; 


TESe tStyleCdoSize, &Styl, 1, TEH); 


break; 
case 5 18Соттага: 
Stul.tsSize = 24; 


TESetStyle(doSize, &Styl, 1, TEH); 


break; 


case plainCommand: 
Styl.tsFace = 0; 
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TESetStyleCdoFace, &Styl, 1, TEH); 
break; 
case boldCommand: 
TEGetStyle((**TEH).selStart, 
&Styl,&lhgt,&ascent, ТЕН); 
Styl.tsFace |= bold; 
TESetStyleCdoFace,&Styl, 1, ТЕН); 
break; 
case ulineCommand: 
TEGetStyleCC**TEHD .selStart, 
&Styl, &lhgt, &ascent , ТЕН); 
Styl.tsFace |= underline; 
TESetStyleCdoFace, &Styl, 1, TEH); 
break; 
case italicCommand: 
TEGetStyleCC**TEHD.selStart, 
&Styl,&lhgt,&ascent, ТЕН), 
Styl.tsFace |= italic; 
TESetStyleCdoFace,&Styl, 1, TEH); 
break; 
case shadowCommand: 
TEGetStyleCC**TEHD .selStart, 
&Styl, &Ihgt,&escent, ТЕН); 
Styl.tsFace |= shadow; 
TESetStule(doFace,kStul,1,TEH); 
break; 


case SuperCommand: 
TEGetStule((**TEH).selStart-1, 
&Styl, &Ihgt, &ascent , ТЕН); 
Styl.tsFont &= REGULAR; 
Styl.tsFont |= SUPER; 
TESetStyleCdoFont, &Sty1, 1, TEH); 
break; 
case RegularCommand: 
TEGetStyleC(**TEH).selStart-1, 
&Styl,&lhgt, &ascent, ТЕН); 
Styl.tsFont &= REGULAR; 
TESetStyleCdoFont , &Styl, 1, ТЕН); 
break; 
case SubCommand: 
TEGetStyleCCF*TEHD.selStart-1, 
&Styl,&lhgt, &ascent, ТЕН); 
Styl.tsFont k= REGULAR; 
Styl.tsFont |= SUB; 
TESetStyleCdoFont, &Styl, 1, ТЕН); 
break; 


default: ; 
ShowSe lect); 


int DoCommandC mResult ) 
long mResult; 


int (һе tem; 
Str255 name; 


theItem = LoWordC mResult 2; 

switch (HiWord(mResult)) 

( cese eppleID: 
GetItem(myMenus[appleM], theItem, &name); 
OpenDeskAcc( &name ); 

SetPortC myWindow 2; 
break; 
case fileID: 
if Ctheltem == fmQuit) returnC0); 
break; 
cese editID: 
if (SystemEditCtheItem- 12770) 
doEditingCtheItem); 
break; 
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HiliteMenu(0); 
return(1); 


MaintainCursor() 


Point pt; 
WindowPeek wPtr; 
GrafPtr savePort; 
Rect TERect ; 


wPtr = (WindowPtr)(WindowPeek)FrontWindowCO; 
if CoursCwPtr )) 


( GetPort( &savePort ); 
SetPort( CGrafPtrOwPtr ); 


GetMouse(&pt); 
TERect = (**TEHD.viewRect; 
if C PtInRect(&pt, &TERect) ) 
SetCursor( &editCursor); 
else 
InitCursor(); 


SetPort( savePort ); 


MaintainMenusC) 


if € !(*(WindowPeek)muWindow).visible || 
lours(FrontWindow()) ) 


EnableItemC myMenusteditM], cutCommand ); 
EnableItemC myMenus[editM], copyCommand ); 


else 


if CCF*TEHD.selStartzzC**TEHD.selEnd) ( 
DisebleItemC myMenusleditM], cutCommand ); 
DisableItemC muMenus[editM], copyCommand ); 


else 


( 
EnableItemC myMenus[editM], cutCommand ); 
EnableItemC myMenusleditM], copyCommand ); 


башка 
CursHandle hCurs; 
hCurs = GetCursor( 1); 
editCursor = **hCurs; 


hCurs = GetCursor(watchCursor ); 
waitCursor = **hCurs; 


ours(w) 
WindowPtr w; 


return CmyWindow!=NULL) && Cw==myWindow) ); 
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C Workshop 


Extend Your Favorite Editor 


Extending Your Editor 
Edit Extender DA 

If you've programmed for awhile, you're bound to to en- 
counter one or two text editors you really feel comfortable with. 
Be it EMACS on a mainframe or QUED on a Mac, a good editor 
has a way of growing on you. You savor the power, the 
flexibility, and all of those little features that really make it stand 
out. Then comes the day, for some reason or another, when 
you're forced to use another editor. You click on the menu bar 
and your favorite feature isn't there. A keyboard command just 
puts a non-ASCII character on the screen. You grit your teeth and 
code away, wishing your preferred editor was around. 

I was rudely awakened to this predicament when І started to 
use MPW and Lightspeed C. QUED had long been my editor of 
choice on the Mac, and I suddenly found a few of my favorite 
features weren't around anymore. Granted, I could continue to 
use QUED or even be more ambitious and write my own editor 
with a little help from Symantec's CAPPS, but I really like the 
notion of an integrated programming environment. To me, it's 
a hassle to transfer from your editor into your main development 
environment all of the time. 

Ah, but that's the joy of being a programmer. You're not 
forever an end user, hoping and praying the software gods will 
deliver you from want. You can rise above the masses with an 
idea and acompiler. The problem of creating an extendible editor 
can easily be solved by simply writing a desk accessory. 

The theory goes like this. You have a chunk of text you want 
to manipulate within your editor. You just select the text, copy 
itinto the clipboard, capitalize/count/do whatever to it, and then 
paste the altered text back in, replacing the previous selection. 
You let the text editor do all of the work, while you sit on top, 
adding your own features through the DA. No sweat, DA spell 
checkers like Thunder! do it all the time. Just combine the 
concepts of the sample “Windows” desk accessory included with 
Lightspeed C with some clipboard related code, and viola, a few 
quick hours of programming gives you the features of your 
favorite editor in a least favored one. Specifically, in the 
following example, capitalization, changing case, word count- 
ing, time and date insertion, and saving a selected region toa text 
file. 


The Clipboard, Fake Keydowns, and Timing 
The obvious storage location for storing text to be manipu- 
lated is the clipboard, alias the desk scrap. Once the text is there, 
itcan be twiddled with to your heart's content. So, the first thing 
to do is get the selected text into it. Now being somewhat lazy in 
not wanting to menu select Copy or Paste or type their keyboard 
equivalents all of the time, I decided there must be a better way, 
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more in tune with the Mac interface. Something along the lines 
of having the text selected, pulling down the DA’s menu, and 
having the command executed. 

The solution is to- post a Command "C" (the non-case 
sensitive, universal Mac key command for “Copy”), and fake the 
editor into thinking the user had just done a copy into the 
clipboard. It'sapretty easy task to postakeydown event with the 
PostEvent trap, but unfortunately you don't have any control 
over the modifiers. If you pass in an ASCII “c” eventCode, and 
a'"keyDwnEvt" eventMsg, all you'll get is a lower case “с” on the 
screen. There are no provisions for specifying that the command/ 
option/shift/caps lock keys may also be pressed. There are two 
choices in dealing with this problem: (1) Post some mousedown 
events with the locations of the “Edit” menu and “Copy” posi- 
tion, essentially faking a menu selection with the mouse. A risky 
proposition since you rely on the editor following Apple's 
interface guidelines of where things should be. (2) Fake the Mac 
into thinking a command modifier key has been pressed. 

The quick and dirty way is to pick door number 2 and modify 
the event queue. Using TMON, the location of the key modifiers 
are readily apparent. (Snoop around at $174 and start pressing 
keys.) Justchangea byte here and there, and presto, the keydown 
“с” event is turned into a Command "C" copy event. The same 
technique can be used when replacing text, by posting a Com- 
mand “V” for paste. You just select a menu item, Edit Extender 
posts a Command “С,” and the text is sitting in the clipboard 
ready for manipulation. 

At this point, things begin to get a bit murky. If you were to 
implement the above method in a desk accessory, you'd see the 
menu bar flash, signalling the Command “С” had been posted, 
but no text would be copied into the clipboard. What's going on 
here? The solution is a matter of timing. The DA has to tell the 
operating system that it's finished, have the application take 
control again to do the copy, and then signal it wants to take 
control again. This can be accomplished with the desk 
accessory's csCode parameter. Just pass in an integer in the 
accRun message and branch as required. With the timing 
problem solved, Edit Extender worked great. I now had some of 
my favorite features up and running. Then I was in for a rude 
surprise. Out of curiosity, I decided to try running it with 
MacWrite and Microsoft Word. It didn’t work at all. Something 
strange was going on. The DA worked fine with MPW, Light- 
speed C, miniEdit, and QUED, but fell flat on its face when it 
came to “real” word processors. 


Private Scraps 


Despite having the same purpose, when itcomes to using the 
clipboard and copying and pasting, text editors and word proces- 
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sors are two different critters. Most word processors that do any 
kind of text formatting (bolding, underlining, italicizing, etc.) 
keep the text they are dealing with in what “Inside Macintosh” 
refers to as a “private scrap.” This is simply a private clipboard 
where the application stores text and formatting information for 
internal use. For the sake of speed and efficiency, when the user 
selects some text and copies or cuts it, more than likely it’s going 
toend up someplace other than the desk scrap. On the other hand, 
virtually every text editor that deals strictly with text, will use the 
desk scrap for storage. This is why you can access copied text 
through the clipboard from the Lightspeed or MPW editor, but 
not from MacWrite or Word. 

The Scrap Manager section of “Inside Macintosh” enlight- 
ens you to the fact that it is good and required programming 
etiquette for an application to transfer its private scrap to the 
common access desk scrap whenever a user quits the program or 
when a desk accessory becomes active. In doing so, formatted 
data should be converted into a form readable by either another 
application or the desk accessory. That means text turns it into 
a type ‘TEXT’ resource (simply a series of ASCII characters), 
graphics become a ‘PICT’ type, and optionally, any formatted 
information can be kept with its own unique resource type. 

I fought off the temptation to cop-out and use Edit Extender 
exclusively with text editors. After all, it might be nice to have 
it work with word processors or even desktop publishing appli- 
cations. So, what determines if a desk accessory is activated or 
not? Simple, if a window that is owned by the DA is brought to 
the front and becomes the active window, the desk accessory 
becomes activated. If another non-DA window comes to the 
front, the DA is deactivated. Not wanting to splash an ugly 
window on the screen, I decided to make my window appear 
offscreen at the upper left corner. Now when Edit Extender got 
a command, it brought the offscreen window to the front, the 
application received a message that a DA had become active and 
converted its private scrap into the desk scrap. The DA goes 
away, and presto, text now awaits us in the desk scrap. 

With the window code working, Edit Extender was in 
business with MacWrite. With the exception of one small detail. 
If you had some formatted text (say italicized Geneva 10) 
selected, and used Edit Extender to capitalize it, when it was 
pasted back in, it came back as Geneva 12 plain. Clearly a case 
of WYDWISYG (What you don't want is what you get!). 
Remember that when the private scrap is converted, it can also 
place formatted data in the desk scrap. That's exactly what 
MacWrite is doing. In addition to the ‘TEXT’ resource, 
MacWrite is placing a 'MWRT'" resource in the desk scrap that 
contains the text with formatting information. When MacWrite 
pastes back in, it will first look in the scrap for a 'MWRT' 
resource, and if it's there, paste it in with all formatting intact. If 
there's none to be found, ‘TEXT’ will be pasted in at Geneva 12. 
The solution to this problem is to get the clipboard format of the 
'MWRT' text. In this case, look at Tech Note #13, MacWrite 
Clipboard Format. Although this version of Edit Extender 
doesn't support formatted text, to do so would be fairly trivial. 
After you've posted the copy event, just scan the desk scrap for 
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a resource with the type “МҰРТ.” If you find it, then based on 
the data structure, go in and find the text and manipulate it. 


Microsoft machinations 

Hmmm. Now it was working with MacWrite, but wasn't 
with Word. Ack! The simple DA was turning into a frustrating 
programming exercise. Oh well, when in doubt, get your 
debugger out. TMON revealed an interesting characteristic in 
Word. In addition to requiring the desk accessory to be activated, 
it also needed a Copy (Command “C”) or Paste (Command “V”) 
event before it would convert its private scrap to the desk scrap. 
Picky, picky, picky. After sliding in the appropriate code, and 
seeing no problems with using it for other applications, Edit 
Extender now seemed to work just fine. (Be advised though, that 
unlike Mac Write, the current version 3.0. whatever doesn’t place 
any formatted text into the clipboard. Rumor has it that future 
versions will place RTF into the desk scrap along with unformat- 
ted text.) 


MultiFinder considerations 

With any desk accessory that interacts directly with an 
application, you need to keep in mind MultiFinder and its buddy 
the DA Handler. Since Mr. DA Handler treats a desk accessory 
like an individual program, I was expecting some major compli- 
cations. I know, Apple says to write small applications instead 
of DAs, but I still like interactive desk accessories. Fortunately 
in their infinite wisdom, the creators of MultiFinder left a nice 
loophole for DAs like Edit Extender. The solution is to hold 
down the Option key when initially selecting and launching the 
desk accessory. That means click on the apple menu, hold down 
the Option key, and select the DA. (If you hold down the option 
key before you select the apple menu, MultiFinder won't display 
any DAs.) Thislittle known technique bypasses the DA Handler, 
and installs Edit Extender (or any other DA for that matter) 
directly into the application's heap. 

(MultiFinder Caveats: In using the Option key method be 
aware of two things. (1) If you get out of memory errors, quit 
the program and increase the application's memory size. (2) 
This technique allows you to run the desk accessory within only 
one application at a time. If you wanted to run Edit Extender in 
(i.e) MacWrite and PageMaker at the same time, just create a 
duplicate of Edit Extender and use ResEdit to give it a different 
DRVR resource name. Font DA/Mover will give it a unique 
resource I.D. when you install it, and you'll be set.) 


Conclusion 

Edit Extender was built so I could have some features 
available no matter which Mac editor I had to use. It demon- 
strates some neat tricks like posting copy and paste events and 
converting text for DA use. But forthe most part, it’s pretty much 
of a base to work off of. I included my pet features, and with a 
bit of coding, so can you. Some other options that could easily 
be incorporated include: sorting, search and replace, paragraph 
numbering, selected text printing, or indexing. Happy editor 
constructing! 
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Figure 1. Project 


Listing EditExtender.c 


/* 
Edit Extender Desk Accessory 
for MacTutor Magazine 
June 1, 1988 
by Joel McNamara, Satori Software 
*/ 
/* the required stuff... */ 
Sinclude “EventMgr .h” 
8include "MenuMgr .h” 
include “MemoryMgr .h” 
t include "FontMgr .h” 
Sinclude "FileMgr.h" 
include “DeviceMgr .h^ 
Sinclude “DialogMgr .h” 
include “Int]Pkg.h” 
include "StdF ilePkg.h^ 


/* the globals... */ 


int ALREADY ОРЕМ = 0; 
int CONDITION = 0; 
int RUNCODE = 0; 
DCt]Ptr DCE; 

GrafPtr SAVEPORT; 


MenuHandle THE_MENUHANDLE; 


/* the constants... */ 

/* routine returns correct resource number for the driver */ 

def ine RsrcID(id) (0xC000 + C"DCE— dCtlRefNum << 5) + id) 

/* the dialogs */ 

Sdefine AboutDLOG 

Sdef ine CountsDLOG 

зде? ine MessageDLOG 

/* counts DITL items */ 

$8def ine Char Item 2 

def ine WordsItem 3 
4 
5 


N — = 


Sdefine SentenceItem 
def ine ParagraphI tem 

/* the fake window */ 
Sdefine FakeWIND 0 
/* run code commands */ 
Sdefine UpperCaseCOND 1 
Sdefine LowerCaseCOND 2 
tdef ine ReverseCaseCOND 3 
Sdef ine CapitalizeCOND 4 
Sdef ine CountsCOND 5 
Sdefine TextCOND 6 
tidef ine DateCOND 7 
8def ine TimeCOND 8 
/* STR8 error messages */ 
Sdefine ListSTR 0 
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зде? ine MemoryMSG 1 
"def ine Gener icMSG 2 
8def ine CreateMSG 3 


Sdefine OpenMSG 4 
Sdefine WriteMSG 5 
8def ine SelectMSG 6 


/* menu items */ 
"def ine AboutITEM 
def ine Upper ITEM 
Sdef ine LowerITEM 
зде? ine ReverseITEM 
8def ine CapitalITEM 
8def ine DateITEM 
Sdef ine ТітеїТЕМ 
def ine CountsITEM 
Sdef ine TextITEM 
8def ine QuitITEM 

/* DA messages */ 
Sdef ine OpenMessage 0 
Sdefine ControlMessage 2 
Sdefine CloseMessage 4 


bn pd uA 
о, ОО O: Qn +. G) — 


/* let’s start... */ 
main(controlParam, dControl, message) 
cntr lParam *controlParam; 

DCtiPtr dControl; 

short message; 


EvQEI tempQElement; 


if (CdControl->dCt1Storage) == 0) ( 
SysBeep(5); 
1f (message == OpenMessage) ( 
SysBeep(5); 
Disp layCMemoryMSG ); 
CloseDr iver (dControl->dCtlRefNum); 


return(2); 


DCE = dControl; 
switch (message) ( 
case OpenMessage: 
DoOpen(); 
break; 


case ControlMessage: 
switch (controlParam-»csCode) ( 

/* who needs to be in control */ 

case accRun: 
if CCRUNCODE != 0) && COSEventAvai 1(keyDownMask, 
&tempQElement) == 0)) 

DoRuncode CRUNCODE 5; 
break; 


case accMenu: 
DoMenu(controlParam-,jcsParam[1]); 
break; 


case goodBye: 
DoGoodBue(); 
break; 
break; 
case CloseMessage: 


DoClose(); 
break; 


return(2); 


/* open the DA */ 
Co 
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DCE-»dCtlFlags |= dNeedLock| 
dNeedGoodBye |dCtl1Enable|dNeedTime; 
DCE-^dCtlDelay = 15; 
DCE->dCtiMenu = RsrcIDC0); 
if (ALREADY. OPEN) 
return; 


RUNCODE = 0; 
ALREADY_OPEN = 1; 
THE_MENUHANDLE = GetMenuC DCE-»dCtlMenu); 


/* about us */ 
lind 


DialogPtr theDialog; 
int dummy; 


theDialog = GetNewDialog(RsrcIDCAboutDL0G),@,-1) 


ModalDialog(@, &dummy); 
DisposDialog( theDialog); 


(*THE_MENUHANDLE )->menuID = DCE->dCt1Menu; ) 
InsertMenu(THE_MENUHANDLE,0); 
DrawMenuBar ( ); /* close everything up */ 
) coe 
/* handle any menu items */ DeleteMenu(DCE->dCt1Menu); 
DoMenuC the! tem) DisposeMenu( THE_MENUHANDLE ); 
int theItem; ALREADY_OPEN = 0; 
( DCE-»dCtlMenu = 0; 
switch (theltem) DCE->dCtlWindow = Ø; 
( DrawMenuBar(); 
case AboutITEM: ) 
DoAbout(); 
break; /* good bue... */ 
DoGoodBye( ) 
case Upper ITEM: ( 
DoCopu(); DCE-»dCtlMenu = 0; 
CONDITION = UpperCaseCOND; DCE-»dCtlWindow = Ø; 
break; 
case LowerITEM: /* do a control c */ 
DoCopy(); DoCopu() 
CONDITION = LowerCaseCOND; ( 
break; struct keus( 
long charCode; 
case ReverseITEM: long modifiers; 
DoCopy(); ) *keysPtr; 
CONDITION = ReverseCaseCOND; long len; 
break; 
GetPor tC&SAVEPORT ); 


case CapitalITEM: 


len = ZeroScrap(); 


DoCopy(); keysPtr = (struct keys*)0x 174; 
CONDITION = CapitalizeCOND; keysPtr-?charCode = 0x00000000; 
break; keysPtr-»modifiers = 0x00008000; 


case Datel TEM: 


PostEvent(3,67); 
keysPtr->charCode = 0х00000000; 


Se tRuncodeC ); keysPtr->modifiers = 0x00000000; 
CONDITION = DateCOND; RUNCODE = 1; 
break; ) 


case TimelTEM: 


/* get the DA’s attention */ 


SetRuncode(); Se tRuncode( ) 
CONDITION = TimeCOND; 
break; RUNCODE = 1; 


case CountsITEM: 


DoCopy(); /* handle any run codes */ 
CONDITION = CountsCOND; DoRuncode(myRunCode ) 
break; short myRunCode; 
case TextITEM: switch (nyRunCode) 
DoCopy(); { 
CONDITION = TextCOND; case 1: /* bring up the dummy window */ 
break; DCE-»dCtlWindow = GetNewWindow(RsrcID(FakeWIND),@,-1); 
CCWindowPeek )(DCE->dCt 1Window))-»windowKind = DCE- 
case QuitITEM: ^ dCtTRef Num; | 
DoClose(); setPort(DCE->dCt1Window); 
break; RUNCODE = 2; 
break; 
default: 
break; case 2: /* do a paste event */ 
) PostPaste(); 
HiliteMenuC0); RUNCODE = 3; 
break; 
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) 


case 3: /* now deal with our commands */ 
DoText(); 


for (loop = 0; loop <= CGetHandleSizeCmyHandle)); 
loop++) ( 
if CisupperC*CCchar. *)((long)(*muHandle) + 100р2222 


break; *((char *)((long)(*newHandle) + loop)) = 
tolower(*((char *)((long)(*muHandle) + 100р222; 

default: else 

break; if Cislower(*(Cchar *)CClong)(*myHandle) + 


/* here’s where we do our edit commands */ 


(1ong2100p222) 
*(Cchar *)CClong)C*newHandle) + loop)) 
toupper(*CCchar. *)CClong)(*myHandle) + loop))); 
else 


DoTextC) *(Cchar *)((long)(*newHandle) + loop?) = *CCchar 
*)(Clong?(*mygHandle) + loop)); 
long len; ) 
long mu0ffset; break; 
long loop; 
long temp; /* the capitalization routine */ 
long  theSecs; case Capital izeCOND: 


Handle myHandle; 
Handle newHandle; 


prevChar = (char)’x’; 
for (loop = 0; loop <= (GetHandleSize(muHandle)); 


Handle theHandle; loop++) 

Rect itemRect; 

int sentences; 1f (loop == 0) 

int paragraphs; ( 

int words; *(Cchar *)CClong)(*newHandle) + loop)) = 

int chars; toupper(*CCchar. *)CClong)(*myHandle) + loop))); 

int itemType; prevChar = %((сһаг *)CClong)(*newHandle) + loop)); 
int tempInt; ) 

char туСһаг; else 

char ргеубһаг, 


DialogPtr theDialog; 


Ptr 


myP tr; 


Str255 numStr; 
Str255 timeStr; 


RUNCODE = 0; 
muHandle = NewHandle(0); 


if ((prevCher == ‘ *) || (prevCher == ‘\r’) || 
(prevChar == ‘\t’)) 
*((сһаг *)CClong?)C*newHandle) + loop)) = 
toupper(*CCchar. *)C€Clong)(*myHandle) + loop))); 


else 
*((char *)((long)(*newHandle) + loop)) = 
%((сһаг *)((long)(*muHandle) + loop)); 


len = GetScrap(myHandle, ’TEXT’, &myOf f set); 
if (Сеп <= Ø) && CCONDITION <= CapitalizeCOND)) 
/* nothing’s in the scrap */ 


ш = *((char *)((long)(*newHandle) + loop)); 


break; 
SusBeep(5); 
Displau(SelectMSG); 
DisposeWindowCDCE-» dCt Window); 
DCE-»dCtlWindow = 0; 


/* a simplistic wc */ 
case CountsCOND: 
chars = sentences = paragraphs = words = 0; 


SetPor tCSAVEPORT ); 
myPtr = *myHandle; 
r (temp = Ø; temp <= len; temp**) 
1f (CONDITION < CountsCOND) myChar = %((сһаг *)(Clong)myPtr + temp); 
/* do we need а handle for manipulation? */ chers**; 


newHandle = NewHandleCGetHandleSizeCmyHandle2); 
if (nyChar == ‘\r’) 


switch (CONDITION) рагадгарћѕ++; 


/* the upper routine */ 


if (muChar == “.” || myChar == ‘!’ || muChar == 727) 


case UpperCaseCOND: sentences++; 
for (loop = Ø; loop <= (GetHandleSizeCmyHandle)); 
100р++) if (myChar == “|| muChar == “Nt? || myChar == "Nr 
*(((char *)(*newHandle)) + loop) = toupper(*((char wordst+; 
x*)((long)(*muHandle) + 100р222; 
break; 
InitCursor(); 
/* the lower case routine */ theDialog = GetNewDialog(RsrcIDCCountsDL0G),8,-1); 
case LowerCaseCOND: SetPor tC theDialog); 


for (loop = 0; loop <= (GetHandleSizeCmyHandle)); 
100р++) NumToString(chars - paragraphs,numStr); 

*((сһаг *)((long)(*newHandle) + loop)) = GetDItem(theDialog,CharItem,&itemTupe,ktheHandle,kitemRect); 
tolower(*((char *)((1ong)(*muHandle) + 100р222; SetIText( theHandle, numStr ); 

break ; NumToStr ing(words,numStr); 

GetDItemCtheDialog,WordsItem,&itemType,&theHandle,&itemRect); 

SetITextCtheHandle,numStr); 

NumToStr ingCsentences, numStr ); 


/* the reverse case routine */ 
case ReverseCaseCOND: 
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GetDItem( theDialog, Sentence! tem, &i temType, & theHandle, &itemRect); 


GetDI tem( theDialog, Paragraph! tem, &i temType, &theHandle, &i temRect); 


) 


SetITextCtheHandle,numStr); 
NunToStr ing(paragraphs, numStr); 


SetITextCtheHandle,numStr); 


ModalDialog(@,&tempInt); 
CloseDialog(CtheDialog); 
break; 


/* text to save condition */ 

case TextCOND: 
Extract(myHandle); 

break; 


/* display date condition */ 

case DateCOND: 
GetDateTimeC&theSecs); 
IUDateStr ingCtheSecs, longDate, &t imeStr); 
PtoCstrCtimeStr); 
ZeroScrap(); 
PutScrap(strlenCtimeStr), TEXT’, &timeStr); 
PostPaste(); 

break; 


/* display time condition */ 

case TimeCOND: 
GetDateTimeC&theSecs); 
IUTimeStringCtheSecs, TRUE, &t imeStr); 
PtoCstrCtimeStr); 
ZeroScrap(); 
PutScrap(strlen(timeStr), ‘TEXT’, &timeStr); 
PostPaste(); 

break; 


default: 
break; 


DisposeWindowCDCE-»dCt Window); 
DCE-»dCtlWindow = Ø; 
SetPort(SAVEPORT); 


1f (CONDITION < CountsCOND) 
/* then we need to paste in the new stuff */ 


ZeroScrap(); 
PutScrap(GetHandleSize(muHandle), TEXT ,*newHandle); 
DisposHandle(newHandle); 

PostPaste(); 


) 
DisposHandle(muHandle); 


CONDITION = Ø; 


/* do a paste event */ 
PostPaste ) 


) 


C theIndex; 


DialogPtr theDialog; 
int dummy; 
Str255 theMessage; 


GetIndString(&theMessage, RsrcIDCListSTR), theIndex); 
InitCursor(); 
theDialog = GetNewDialogC(RsrcID(MessageDL06),0, - 1) 
ParamText( theMessage, “\p”, “Ар”, ^p^); 
ModalDialog(@,&dummy); 

) DisposDialog(theDialog); 


/* save selected text toa file */ 
Extract(muHandle) 
on myHandle; 


4 


SFReply myReply; 

Point туос; 

int errCode, refNum; 
long  theCount; 


myLoc.v 
myLoc.h 


90; 
90; 


HLock(muHandle); 
SFPutFile(muLoc,*VpSave selected text 
to:”,*\pUntitled”, OL, &myReply); 


CmyReply.good) 


errCode = 
CreateCmyReply.fName,myReply.vRefNum, ‘EDIT’, TEXT ); 
1f CerrCode != noErr); 


if CerrCode == dupFNErr) ( 
FSDeleteCmyReply.fName,myReply.vRef Num); 
errCode = Create(myReply.fName,myReply. vRefNum, 
^EDIT', TEXT ); 
else 1f (errCode != noErr) ( 
Displau(CreateMSG); 
HUnlock(muHandle); 
jum 


) 


1f CFSOpenCmyReply.fName, myReply.vRefNum,&refNum) !- 
noErr) { 
DisplayCOpenMSG); 
FSCloseCrefNum); 
HUnlock(mgHandle); 
return; 


theCount = GetHandleSize(myHandle?); 
if (FSWriteCrefNum,&theCount, *myHandle) != noErr) ( 
Display(WriteMS6); 


struct keys{ 
long charCode; 
long modifiers; 
) *keysPtr; 


keysPtr = (struct keys*)@x 174; 
keysPtr-?charCode = 0x00000000; 
keysPtr-»modifiers = 0x00008000; 
PostEvent(3, 86); 
keysPtr->charCode = 0x00000000; 
keysPtr-»modifiers = 0x00000000; 


/* error message display */ 
Disp lay( the Index ) 
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FSCloseCrefNum); 

HUnlockCmyHandle?); 

return; 
FSCloseCrefNum); 


HUnlockCmgHandle); 


/* just in case your compiler doesn’t already have these... 


otherwise, leave them out... */ 


strlen(s) 
register char *s; 
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char *sÜ = s; 


while (*s++); 
return (s-s0- 1); 


int toupper(c) 
char c; 


return((c)=’a’) && Cct?z^) ? (c-32) : c); 


int tolower(c) 
char c; 


returnCCc?)2/A^) && Cc« 72^) ? (c+32) : с); 


int isupper(c) 
char c; 


return((c)=’A’) && Ccqc 2/05; 


int islower(c) 
char c; 


return((c)=’a’) && (с<-72722; 


Listing: EditExtender.r 

* resource file for Edit Extender DA 
* by Joel McNamara 

* for MacTutor Magazine 

* June 1, 1988 


EditExtender .rsrc 


TYPE DLOG 
," 16000 
blah blah 
54 74 190 452 
Visible NoGoAway 
1 
0 
- 16000 


ТҮРЕ 01/00 
,715999 

Counts 

264 20 330 494 

Visible NoGoAway 

0 


0 
- 15999 
э б 

ТҮРЕ 0106 

,715998 
info 
68 120 152 408 
Visible NoGoAwau 
1 
0 
- 15998 


TYPE DITL 
,- 16000 
4 
staticText Disabled 
4 10 22 330 
Edit Extender version 1.0 - bu Joel McNamara 


button 
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109 274 129 353 
OK 


staticText Disabled 
112 7 129 210 
For MacTutor Magazine 


staticText Disabled 

38 21 96 364 

Edit Extender is a series of helpful tools, not found in all 
text editors. Use the Edit Extender DA to change, insert, and 
analyze selected text in your documents. 


TYPE DITL 
,7 15999 
10 
button 
32 367 51 443 
OK 


staticText Disabled 
T 89 27 149 
999999 


staticText Disabled 
32 88 52 149 i 
999999 


staticText Disabled 
32 257 52 318 
999999 


staticText Disabled 
1 257 27 318 
999999 


-40 -40 -20 -20 
Visible NoGoAwau 
0 


staticText Disabled | g 
7 8 27 87 


Characters: TYPE MENU 


, 16000 
staticText Disabled 


32 8 52 56 About Edit Extender... 
Words: (- 

Upper case 
steticText Disabled | Lower case 
32 171 52 246 Reverse case 
Sentences: Capitalize 

(- 


staticText Disabled | Current date 


T 111 27 255 Current time 
Paragraphs: (- 
Counts 
staticText Disabled (- 
6 346 25 463 Save selection as... 4 
Text Information (= 
Quit 
TYPE DITL 
, 15998 TYPE STR: 
3 ,- 16000) 
button. 6 
60 195 79 263 Sorry, not enough memory for Edit 
OK Extender to run. 
| белегіс еггог! 
staticText Disabled | Sorry, couldn't create the text file. 
8 49 56 272 


Я Sorry, couldn’t open the text file you 
0 just created. 
Sorry, couldn't write the selected text 


iconItem Disabled to a text file. 


8 8 40 40 You must have text selected before 

0 performing а Edit Extender command. 

TYPE WIND = 
2515000 5%) 

Dummu СЕ 
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C Objects 
Pseudo Objects 


Adam Treister is the president of For Your Information in 
Santa Barbara, CA, and, when not spending too much time 
writing this article, is putting the finishing touches on Com- 
mander Bond’s Briefcase, a collection of vertical market and 
small business calculations. He would love feedback on the 
article, and to have others implement more drawing features апа 
send them to AppleLink D3474. 


Evolution of the Macintosh 

I recently attended опе day of the Apple Worldwide Devel- 
opers Conference 89, and quickly caught the thrust of Apple's 
unambiguous message to developers. To quote one of the slides 
(and Greg Williams) “If you don't learn object-oriented pro- 
gramming now, you will not be able to program the Macintosh 
later." There is not a lot of room for interpretation there. When 
C++ becomes available, a large number of C programmers will 
be switching to it. With the standardization offered by a joint 
development between Apple and AT&T, the nice extensions 
C++ adds to straight C programming, the support of Object 
Oriented Programming and the object libraries available through 
MacApp and other sources, C++ seems to be destined to become 
a standard Macintosh language. 

From what I heard, few developers were arguing with 
Apple's hard line support of Object Oriented Programming. 
After all, the evolution of the Macintosh is looking pretty solid. 
The Mac is reaffirming its roots in the object oriented environ- 
ment of the Xerox Star. It is striving to become a large scale 
operating system with virtual memory and (someday) true multi- 
tasking, and it is moving to a software environment that allows 
maximum flexibility and maintainability. And, a few years 
down the road, just when OS/2 is finally overcoming the ob- 
stacles of its own weight and poor design, the Macintosh, on the 
foundation of a (then) completely object oriented software base, 
will be in a position to make a seamless transition to multiproces- 
sor architectures, and blow the blue suits out of the water. 


A Gentle Transition 

With these dreams as our beacon, and the dogcow cheering 
us onward, developers will look to C++ as a way to shift into 
object oriented programming without sacrificing performance. 
Yet there seemed to be a collective angst amongst the C program- 
mers, that the transition to C++ will be a long and burdensome 
one and that the costs will be high. Personally, I don’t expect the 
transition to be that overwhelming. There is no complete rewrite 
necessary, as there is when switching between two syntactically 
different languages. C++ includes all of C, and the compiler will 
not be grading you on how object oriented your code is. The 
transition can be gradual, at your own speed, and within your own 
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style. The additional features of C++ should encourage good 
programming style, rather than choke on any of your existing bad 
habits. 

As part of my own transition to C++, I have written here a 
program in a "pseudo" object oriented style. It is meant to 
demonstrate that object oriented programming is as much a style 
of programming as a characteristic of a language. Itis also meant 
to put my code into a style such that, when I switch to C++, I will 
only need to make some textual substitutions rather than to 
completely restructure my applications. 


True Object Oriented Programming 
Definitionally, an object oriented language must satisfy all 
of the following properties: 
data abstraction 
inheritance 
polymorphism 
dynamic binding 


This program will implement the first three properties in 
conventional C code. I will also discuss a possible implementa- 
tion of the last property, though it will not be implemented, both 
for the implementation problems as well as the conceptual 
obscurity of dynamic binding. Because of that short-coming, the 
occasional complete disregard for the objects when I felt I could 
speed up the code, and for the love of a good acronym, we cannot 
Claim this program matches the defintion of object-oriented 
languages. Instead, I will call it Pseudo Object Oriented Pro- 
gramming. 

In this code are actually two entities, which may be of 
interest to the reader. The first is a small shell, handling the start- 
up, main event loop, and shutdown responsibilities, and dis- 
patching messages to the window objects who take over from 
there. This POOPShell (consisting of the first two program 
modules) is much the same event handling shell that I use in my 
commercial programs. It is almost a mini- MacApp in a few 
pages of source code. The second part, POOPDraw is an actual 
application, a MacDraw clone, which almost ranks as a real 
program. І hope that this program may act as the starting point 
for your drawing programs or drawing portions of larger pro- 
grams. Although POOPDraw is only the starting point for larger 
applications, I think there is a vast potential for adding graphical 
editing capablities to a wide variety of programs, which may not 
ever get them if the programmer has to start from scratch. 
Hopefully, this program will provide a module with the neces- 
sary capabilities to let you add simple graphic editing to your 
applications. If this is the case (and I hope you'll let me know if 
it is), then we may together verify all the good things Apple is 
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preaching about the drop-in extensibility of object oriented 
programming. 

First, I will give a brief description of the organization of 
POOPShell and POOPDraw, and then discuss how it fulfills (or 
does not) the criteria of object oriented programming. There are 
many places where I will rely on conventions or self-imposed 
practices to gain advantages that are inherent in true object 
oriented languages. But the point of this article is that the 
concepts of C++ and Object Oriented Programming are notreally 
that new to most of you. You may need to learn the extra syntax 
of an expanded language, but the philosophy of Object Oriented 
Programming will probably end up looking like an elegant 
manifestation of all the good habits you've been trying to 
maintain all along. 


Objects and the POOPShell 

Anobject, as used in this program, is a handle, just like in any 
other Macintosh program. It is created like any other handle, 
through the standard routines of the Memory Manager. I use one 
of my favorite macros called _GetHandleToRecord() which 
takes as its argument the typedef of a structure and returns a 
handle to that many bytes, after checking that all went well. The 
function which creates the new object (poignantly called New) 
initializes the object to know its own identity, from that point on, 
the object is held be responsible for all messages that might be 
passed to it. To the program as a whole, all objects are of the 
generic type ObjectHandle, but once a message is passed to this 
object, it will provide the access to the private workings of its 
Class. 

The early Greeks are rarely credited for their work in 
Compiler Design, but if they had been into it, Archimedes would 
have been quoted as saying: “Give me a good jump table and I 
won’t have to carry this 2x4 around with me all the time.” The 
crux of this article is that one well-placed switch statement can 
turn C into a sufficiently object oriented language. 

By convention, the first several fields in the structure of any 
object are reserved for those which are common to all objects. 
Only the first field is truly necessary to accomplish modularity of 
code, but I’ve also included a few other fields which I’ve 
arbitrarily chosen as a list of fields I think all objects should have. 
The list is cut down to the minimum for this article, but you can 
easily add your own standard fields by modifying the macro. All 
standard fields are conveniently included in all objects by con- 
densing all of their declarations into a macro called _StdOb- 
jectFields, which all objects must include at the top of their type 
declaration: 


/* The field decls common to all objects */ 


"define .FLD1 void (*dispatch)(); 
"define .FLD2 WindowPtr port; 
define .FLD3 short class; 
define .FLD4 int length; 
define .FLD5 Rect bounds; 
"define .FLD6 longattributes; 


"define .StdObjectFields FLD1 .FLD2 FLD3 \ 
-FL04 .FLD5 .FLD6 
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/** This macro is included in the structure definition of all 
objects. For example, a hypothetical object declaration might 
eppear: **/ 


typedef struct 


-Std0bjectFields 
/* object specific fields go here */ 
) HypoObjRec, *HypoObjPtr, **HypoObjHandle; 


The first field of all objects, and the one crucial to this whole 
implementation, is a function pointer called dispatch. Upon 
creation of a new object, we initialize this field to point to a 
function specific to this class of object. The function contains 
little more than a switch statement, which looks at the parameter 
called Message, and according to its contents, calls some other 
function. All of the object's routines are declared static (which 
I #define into private) and are known only to this particular class 
of object. This establishes a single entry point to all of the 
methods for any given object, much as the ListManager or 
Packages have a single trap anda selector field, which determines 
the functionality within the trap call. 

The ParmP parameter is a pointer to a long, which means 
who knows what it points to. It is a wildcard pointer, which will 
mean different things in each function call. If the call only has 
one parameter, ParmP points to it. If there are multiple parame- 
ters, ParmP is an array of pointers. Surprisingly, the entire 
POOPDraw only has one function with more than one parameter, 
and it has two parameters, and though it is risky practice to send 
blind pointers around, the potential errors it causes are easily 
recognized and not too pesky. (Yes, a hack is a hack.) 


To dispatch any message, you simply call the function 
DispatchCOb jectH, message, ParmP ); 


Dispatch checks that the object exists, pulls out the function 
pointer, and invokes it: 


void DispatchCObjectH, Message, ParmP) ObjectHandle ObjectH; 
int Message; 

LPtr ParmP; 

( if CObjectH) 
(*(*0bjectH)» dispatch )(ObjectH, Message,ParmP); ) 

This will send execution into the object’s local ObjDispatch 
function: 


0b jDispatchCObjectH, message, inParm, outParm) 
DrawPanelHandle ObjectH; 

int message, 

Ріг inParm,outParm; 


switch (message) 


case DISPOSE: 
break; 
case KEYDOWN: 
break; 
case MOUSEDOWN: MouseDown(0bjectH); 
break; 
case UPDATE: 
break; 


DisposeCObjectH); 
KeyDown(0bjectH); 


Update(ObjectH); 


/* more messages down here */ 
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This extra jump table actually adds little or no overhead to 
the program because it will elimitate many others that would 
otherwise be scattered throughout the code. For example, to 
draw a graphic element in a non-object oriented approach, you 
may include code of the form: 


ү ((*ObjectH)-,class) 


case RECT: DrawRect(element); 
break; 

case OVAL: DrawOvalCelement); 
break; 

case LINE: DrawLineCelement); 
break; 


whereas in this program, your draw routine will look like 
this: 


DispatchCelement, DRAW, NULL 2; 


regardless of what kind of object you are drawing. 


The beauty of this approach is that when you later expand the 
program, for example by adding Bezier Curves as a new graphic 
element, you simply add all of the methods in the module with the 
new object, and do not have to modify the Dispose, Activate, 
Mousedown, Keydown, Update, etc routines of your shell to add 
the extrahandlers. The objectitself, through the function pointer 
in the dispatch field, will know where to call the methods it 
understands. For those of you who use prototypes to check 
parameters (and if you don’t, you should!) this also means that 
you need only to include the prototypes in one module, and not 
throughout the entire project. This will save many global 
recompilations, when you make changes to the parameter lists of 
your functions. Admittedly this wanton disregard for strongly 
typed pointers undermines much of the effectiveness of using 
prototypes, but they are still valuable within object modules. 

The single exception to this modularity is the New function, 
which is responsible for creating all objects known to the pro- 
gram. Since amessage can’t be dispatched to the function pointer 
of an object not yet created, the New function for any additional 
classes must be added to the appropriate application-specific 
module. True object oriented languages also handle new slightly 
different than other messages, but they do it more gracefully than 
Ido here. But this implementation is better than allowing any 
piece of code to create new objects directly, because it localizes 
where the changes must be made, and limits recompilation to a 
single small module, instead of forcing a global recompile. Italso 
centralizes the creation process, allowing for error checking (not 
that I ever do error-checking) of new objects to be performed all 
in the same place. 

Toolbox objects which have a refCon field (Windows, 
Menus, Controls, etc.), should insert the objectHandle into their 
refCon field. This allows a smooth interaction between the 
toolbox calls and the POOPShell. The only such objects I use 
here are Windows. To facillitate their handling of Windows, I 
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have yet another function WDispatch which allows the passing 
of a WindowPtr instead of always having to extract the refCon. 
This smoothes the interface with routines like FrontWindow() 
апа FindWindow(), which are used throughout most Macintosh 
programs. 

A possible improvement (at least in terms of execution 
speed) would be to implement Dispatch and WDispatch as 
macros instead of functions. Because they are called so oftten, 
this change could cut the size of the stack almost in half. But, for 
didactic and debugging purposes, itis valuable to be able to trace 
through the Dispatch function. More importantly, my attempt to 
implement those macros introduced some nasty interactions 
between the calls of the function pointer and the surrounding 
code. 


POOPDraw 

I will say very little about the application itself. It is a 
MacDraw-clone, which is truly the prototypical object oriented 
program example. Each graphic element you draw is an object, 
as are the window, and the view, which handles to the content 
region of the window. The tool palette is a cheap hack, using a 
single picture resource as the whole palette, instead of fifteen 
separate objects each with their own pictures and event handlers. 
Itis actually implemented this way intentionally, as an example 
of when itseasier to just cheat than to create real objects. A better 
job would use Thomas Fruin's tear-off windowing techniques 
(MacTutor, 12/88), making TWindow objects. 

In the last minute scramble, to finish a long overdue project, 
I am axing many expected features, which any real application 
must have. Major examples include printing, scrolling and the 
entire Edit menu. We'll leave that stuff as exercises for the 
reader. I did implement a basic file I/O scheme, because that’s 
usually omitted from this type of article and is great code to steal 
if you've never done it or written it yourself. I thought it would 
be elegant code and simple to add. As it turned out, it was neither. 

Lisp programmers may appreciate the inclusion of a List 
object, and the implementation of the Apply command, one of the 
nicer features of that wonderful language. Simply put, if you 
send a message to a List object it will dispatch the message to 
everyone in the list, getting a lot of work done with one call. The 
list structure is implemented with a dynamically resizing array, 
instead of the traditional doubly linked list. This makes it 
possible to include objects in any number of lists, with minimum 
overhead and maximum speed. 


Fitting the definition 

Now, let us re-examine the definition of Object Oriented 
Programming, and establish the extent to which POOPShell 
satisfies the textbook. Iam not trying to establish the POOPShell 
as an example of true Object Oriented Programming, rather 
trying to teach something about Object Oriented Programming 
by showing what it is and what itisn’t. I don’t want to convince 
anyone to adopt my methods instead of C++, rather I want to ease 
the transition to that richer language through a half-way implem- 
entation. I do claim that if you shift from traditional program 
structure to a POOP-ier structure, the ultimate conversion to C++ 
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might be easier. 


Data Abstraction 

The primary tenet of object oriented programming is Data 
Abstraction. This is a very fundamental concept, meant to avoid 
incorrect access of data. All C programmers employ it, but there 
are limitations to data abstraction in C which C++ will transcend. 

The most significant “breakthrough experience” I had in my 
education into programming was when I made the transition 
from Basic to Pascal, and my introduction to structured program- 
ming. Here was a language and a vocabulary which embodied all 
of the good practices I struggled to maintain in my early pro- 
grams. In many ways, Pascal enforced good programming style 
upon me, requiring me to declare variables, and making me be 
aware of which constructs were static (declared in the code) and 
which were dynamic (created with new statement and managed 
through pointers). As I became familiar with all the added rules 
and restrictions, I realized the extra work paid off immensely. 
The biggest impact was that I was no longer simply applying 
instructions to a machine; suddenly I was modelling a problem. 
The addition of complex data structures, made up of an infinitely 
expandable list of simpler ones united the process of problem 
solving with coding, and gave me a new insight into the interre- 
lation between data structures and algorithms. 

Now, I see that structured programming is only a midway 
station en route to object oriented programming. The elegance 
of structured programming still does not completely encapsulate 
data from accidental intrusion, it does not completely embody the 
correlation between the data and algorithms, even though thi is 
an integral part of the conceptual thrust of Pascal (as evidenced 
by the title of Wirth’s book: Data Structures + Algorithms = 
Programs). 

We all are familiar with the difference between using local 
and global variables. Local variables are admittedly more 
trouble, as they require declaration in each routine (and much of 
compile-time debugging is devoted to declaring local variables), 
but the security and clarity they provide is almost universally 
accepted as worth the extra effort. What local variables do not 
provide, though, is the ability for two or more routines to access 
a variable, but still have it be “local” insofar as that other routines 
cannot change it. This is accomplished in true Object Oriented 
Language’s by encapsulating the data within the object and only 
allowing access through a method associated with the object. 

C does not offer quite that clear a definition, but, by limiting 
the scope of declarations to a single compile-unit or module, this 
is sufficiently accomplished. If you follow the common sense 
rule that an object’s structure definition is declared in a single 
module and never referenced externally, then no one outside of 
the module can access those fields from outside the methods of 
the object. In this way, the C compiler will catch any accidental 
references to the private fields of an object. Ina simple sense, 
the difference between data abstraction in C and C++ is not 
terribly significant. The latter allows more control over the level 
of protection, but the former offers plenty to those who are 
willing to obey the common sense rules of good programming 
style. 
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Inheritance 

Whereas data abstraction is probably nothing new to you, it 
is quite likely that inheritance is a new concept. Inheritance is 
defined as the ability for a object to be specified as an descendent 
of another object, and, in the absence of overriding instructions, 
to assume the behaviour of the ancestor. As an example, all 
objects in POOPDraw have a bounds rectangle associated with 
them. Therefore, when I want to access the bounds rectangle of 
a text box, I do not have to write code which performs that 
function. The textbox, as a descendent of the standard object, 
will inherit that function, unless I specify that it should not. 

If you tend to cut and paste code around to create new 
applications from old ones (and who doesn’t), then it won’t take 
you long to really benefit from the inheritance properties of C++. 
Once you establish an object in an old application, that piece of 
code, tested and debugged, will be usable in your newer applica- 
tions. You call the older version the parent, and only the changes 
needed for newer application need to be written from scratch. 

Inheritance is very simple to implement in this program. We 
have already discussed how all of the known messages under- 
stood by an object are implemented as case clauses within a 
switch statement. All inherited capabilities are accessed through 
the default clause. In traditional C programming, if none of the 
cases match, either nothing happens or, if the programmer is 
conscientious, an error handler is invoked. In this program, if the 
object does not understand a message, it will simply pass the 
message along to its parent class. At the topmost level, it is 
considered an error if a message is unrecognized, but at all lower 
levels, the default case is simply a call to another jump table. 

Normally, the relationship of an objectto a classis analagous 
to the that between an individual and her race. An object is an 
instantiation of a class. In true Object Oriented Languages, the 
parent of an object is an object itself, with its own data. In the 
POOPShell implementation, the parent is a class, but not an 
object. Instead, the class specifies where to look for a method if 
it is undefined, instead of naming an object which may know. 
This interferes with the implementation of dynamic binding, as 
discussed below, but is sufficient for providing the property of 
inheritance, and decreases the required message-passing over- 
head. 

Seeing the tree structure of inheritance can be obscured by 
the separate tree structure associates with the dispatch of events 
down from the main event loop. Figure 1 shows a downward 
flow of execution first through “event links" and then through 
"inheritance links". 


Polymorphism 

Polymorphism is defined as the ability for different objects 
to respond differently to the same message. As an example, an 
Oval and a Line will not execute the same code in response to a 
command to DRAW, but they will both understand the com- 
mand. 

In C, any function declaration preceded by the key word 
static, specifies that the function may be called only within the 
module where it is declared. The linker will not complain if 
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i Chain of Events 
Links 


оооп Inheritance Links 


Figure 1 


multiple static functions with the same name exist in different 
modules of a program. That is to say, C is a polymorphic 
language. 

That is not to say that C++ isn’t better. C++ incorporates 
overloading, which allows more than one non-static function to 
have the same name, and different parameters. I plan to use this 
feature extensively with Quickdraw, to reduce the common 
practice of breaking points into h and v, or transforming two 
points into arectangle. But there is nothing that overloading can 
do that you can’t manage with mangled pointers or #define. 
Therefore, it can be said that C programming in general, and the 
POOPShell in particular, are truly polymorphous perverse. 


Dynamic Binding 

The final criterion of true Object Oriented Programming, 
and the one omitted from this implementation, is dynamic 
binding. With dynamic binding, it is possible to change, at run- 
time, an object’s inheritance path or its response to a message. In 
my mind, this is conceptually rather than technically difficult. 
Anexample of dynamic binding in practice is the way HyperCard 
attaches scripts to buttons and fields. In the course of running the 
program, the user is able to change the behavior of buttons and 
fields. But, apart from environments which are user program- 
mable and hypertextual, there aren’t many examples of dynamic 
binding obvious in programs I know of. So, brazen in my 
ignorance, I have chosen to wait to implement this feature until 
someone can give me a good reason to do so. 

The method to implement dynamic binding is relatively 
simple. If we were to change the dispatch function pointer of an 
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object to that of a different object, from that point on, the object 
would behave differently. So, adding dynamic binding to 
POOPDraw is as simple as adding a method to change the 
dispatching function. (You should also change the class field, so 
that the object does not suffer an identiy crisis, but that actually 
may not be necessary.) 

Adding dynamic binding would require a only few substan- 
tial changes to the structure of POOPShell. In the current 
implementation, when the default clause of an object's dispatch- 
ing function does not recognize a message, it calls a parent 
function, whose name is hard-coded into the dispatch funtion. 
To allow dynamic binding, the object would instead contain a 
field naming its parent. The parent itself would be a true object, 
requiring a globally declared object for each class to be created 
atstart-up. Then, in the case a message is not recognized, the 
object would call: 


DispatchCC*0bjectH2-»parent, Message, ParmP); 


Dynamic binding would be achieved by giving the object 
the ability to change the value stored in the parent field. 

One interesting advantage of this alternate method, would be 
that it would be possible to name not a single parent but multiple 
parents of an object. That is, our "language" would implement 
multiple inheritence, where an object can be defined as the 
descendent of several classes and have the abilities of all of the 
them. As an example, a tear-off palette might be the descendent 
of a window, a menu, a picture and a rectangle. It would 
understand the messages to any of these elements without any 
code unique to itself. Multiple inheritance, a gem of conceptual 
gadgetry, employed by only the most object oriented purists, and 
lost on “the rest of us", is not implemented in the upcoming 
release of C++. 


Objects in the Real World 

This may be a good place to discuss the real world consid- 
erations of Object Oriented Programming. It is a fine line 
between how much is good modularity and the point when the 
concepts may instead burden the implementation. A good 
example is а rectangle. Here I don't mean the graphical element 
in POOPDraw, but rather the Quickdraw rectangle, as is in the 
bounds field in every object. In Smalltalk, the truest object 
oriented language I know of, every data structure, be ita window, 
a rectangle or an integer, is an object. This adds substantial 
overhead to every operation, and bogs down the system fairly 
quickly. As a C programmer, I want my code to be fast. Even 
when the difference is only a few instructions, and may be 
unnoticable to the user, the code seems to read better (to me) 
when I know it doesn't unnecessarily waste time or memory. 

If all of the rectangles in this program were objects instead 
of Rects, they would each require about four times the memory 
as a simple static structure. Because the rectangle is a parent to 
just about everyone, dispatching any message to a rectangle 
object would mean traversing several jump tables, dereferencing 
all kinds of handles, pushing several activation records onto the 
Stack, and popping them all off on the way out. The time required 
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to perform: foreign void ApplicationShutDown (void); 


жж EE EE EE EE EEEEEOE E GE / 
Dispatch(rectangle, WIDTH, NULL , &answer ); /* THE GLOBAL DECLARATIONS x/ 


/SRF2XX333X51XXXXXXXXXXXXXXXXXXX5XXXXXXXXXXXXXXXXXXKKXKXK/ 
could easily be a hundred times as long as 

MenuHandle ` Menus[NUMMENUS]); 

EventRecordEvent; /* the Event Record */ 


rectangle.right - rectangle. left. long LastMouseDown = 0: /* time of last mouse down */ 
Boolean MillerTime = false; /* Quit flag */ 
Iam willing to expend the extra overhead tohaveafunction | int errno, 
Width(r) in my library, but not to have a true object. This is a у */ 
personal compromise, but it is my suspicion that the transition /* MAIN */ 
from C to C++, will be an exercise in balancing speed and | /% Тһе standard shit - init, узан? 
familiarity vs. elegance and modularity. Calling statically bound 55426 / 
methods in C++ is optimized and much faster than it would be in 
the POOPShell, but it still takes over twice as long as calling a Макеурс); 
function. Му opinion is that, іп (ће case of simple program нол 
elements (like numerical types, strings, rectangles, etc.), objects 
libraries should not replace standard function libraries, espe- T , 


cially if you consider the fact that your function libraries are | у» WAKE UP */ 

already written, debugged and understood. Remember, those are fins function initialises the Mac Toolbox, creates */ 
the attributes which attract us to C++ in the first place. It would Қайы bar and calls рр сати specific init routine %/ 
becounter-productive to abandon methods that work and that are 


fast, for the sake of conceptual purity. "ds WakeUp() 
WindowPtr win; 
To Boldly Go... register int i; 
The real beauty of C++ is that it is a superset of C, and any extern — MenuHandle Menusi]; 
program you have should compile and run in C++ without InitMacintoshO; 
modification. The pressure for change all at once is minimal. But TurnWatchOn(); 


the new language adds many of the extensions C has been 


кйин Ñ : for (i=0; i < NUMMENUS; i++ ) 
missing, and opens the door to a new paradigm of programming. ( 


Look forward to a broadening mental transformation, as the C Menus[i] = GetMenuCi + AppleMenuID- 12; 
vocabulary expands onto new and vast conceptual frontiers. InsertMenu(Menus[1], 0); 
[Due to the size of the application Adam submitted, we are AddResMenu(Menus (2) , ^DRVR ^; 
unable to publish in the journal a full listing. Save your fingers DrawMenuBar(); 
andget the source code disk if you want POOPDraw. The 5506 
following is а partial listing to give you some idea of the TurnArrow0n(); , 
application. -ed] ) 
Listing: Main.c ү, SS c 2 */ : 
[ CXOooooopboponopeoopbonopeonoeoeooooooeoeonenoeonoopboeeerr / неба лус А aet the sois ción КҮ” 
* THE POOP SHELL х : I 
иво eee tt there any windows open they are closed. */ 
/* An Adventure in Pseudo-Object-Oriented-Programming */ id Die) 
ARGO OO OAT III И уота ше 
/* : ‚ 
£ >>) File name: Main 517255 message, ctStr,sizStr; 
* уу) Purpose: The main, start-up and shutdown routines ; 
* >>> Project: PoopDraw while (MyFrontWindow()) 
* ››› Date: June 5, 1989 | 
ж >>> By: Adam Treister ) WDispatch(MuUFrontWindow(),CLOSE,NULL ); 
x . ғ 
еони тонап) 
/*For Your Information 1802 Hillside Rd. SB CA 93101 */ ) xitloShell(); 


/®*®*Ж®ЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖАААЖЖАЖАЖАЖАЖЖЖАЖЖЖЖЖЖЖЖАЖЖАЖЖЖЖАЖЖЖЖЖЖЖЖЖЖХ / 


1; 
Sinclude “PoopDrawInc” [* / 


/*send messages to the appropriate object 
* 


[BERARERERER RARER REAR REESE RERERA AER AA AAA ERA A AAR EAAAE RE / o 
void DispatchCObjectH, Message, ParmP ) 
main (void): ObjectHandle ObjectH; 
i ; (void): int Message; 
private void WakeUp (void); in Ç 
private void Die (void); ral ParmP; 
foreign void Twiddle (void); if (ObjectH) 


foreign void ApplicationInit (void); (*(*0bjectH)->dispatch)(ObjectH, Message, ParmP ); 
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| a. M P p -— / 
/*A special case of Dispatch exclusively for windows. 
х-------------------Х/ 


void WDispatch(wP,Message,ParmP) 
WindowPtr wP; 

int Message; 

LPtr ParmP; 


ObjectHandle obj; 
obj = CObjectHandle) GetWRefConCwP ); 
if Cobj) €*C*obj)->dispatch)Cobj,Message, ParmP 5; 


Listing: EvtHandlers.c 


/ BRRRERERERAKRARA EERE EERE RAKE ХХ ХХХ ХХХ ХХ ХХХ ХХХ ХХХ ХХХ ХА / 
/* THE POOP SHELL */ 


/YKYXXXXXXX1XXX1XXXXXXXXXXXKXXXKXXKXXXKEXKKXKXXXKXXKXKXKXXXKXKXKKXKK / 


/* An Adventure in Pseudo-Object-Oriented-Programming */ 
/^*%ХЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖ / 
/* 

ж о) File name: 
ж ))) Purpose: 


EventHandlers 

main event loop (Twiddle) and other high 
level event handlers 

Briefcase 

April 5, 1989 

Adam Treister 


* >>> Project: 
ж yy Date: 

х >>> By: 

*/ 
/®ХЖЖХЖЖЖЖХЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ / 


/*For Your Information 1802 Hillside Rd. SB СА 93101 */ 
/^^*Ж*ЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖХАЖАЖЖЖЖАЖЖАЖЖЖЖЖЖЖХ / 


Sinclude “PoopDrawInc” 
void DoMenuCommand (long MenuSelectResult); 


public void Twiddle (void); 

private void DoMouseDown (EventRecord Event); 

private void DoMouseUp (EventRecord Event); 

private Boolean ClickIsInActiveWindow CWindowPtr ClickedWin- 
dow); 


private void DoKeyDown (EventRecord Event); 
private void DoUpdate (WindowPtr ҰР); 
private void DoActivate — (EventRecord Event); 
private void DoSuspendResume (void); 

/* wi T х/ 

/* MAIN EVENT LOOP */ 

% ——— “/ 


үр» Twiddle() 


extern EventRecord Event; 

extern Boolean MillerTime; 
register long Sleep = 10; 
register Boolean EventPending; 
register WindowPtr wP; 


oe C!MillerTime) 
EventPending = 


&Event, Sleep, NULL); 
і? (EventPending) 


Wai tNextEventCeveryEvent, 


тт (Event.what) 


case mouseDown:  DoMouseDown(Event); break; 
case mouseUp: DoMouseUp(Event); 
break; 
case keyDown: 
case autokey: DoKeyDown(Event ); 
break; 
case updateEvt: DoUpdate(CWindowP tr Event .message?; 
break; 
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case activateEvt: DoActivate(CEvent); 
шы 


) /* if EventPending*/ 
else 


if (OurWindow(wP = 
WDispatch(wP,IDLE,NULL); 


))) 


Boolean DoubleClicked; /* last mouse down was a double */ 


MyFrontWindowC22) 


private long LastMouseUp; 

privete Point LastMouseUpLoc; /*not used for now */ 
Jx ---------------- */ 

/* DO MOUSE DOWN */ 


/*This function handles mousedown event. FindWindow is */ 
/*called to find which window the mouse is in. Then event */ 
/*is “Dispatched” there. */ 


*/ 
void DoMouseDown(Event) 
EventRecordEvent; 
WindowPtr WhichWindow; /* the event window */ 
register Point MousePosition; /* current mouse pos */ 


register int Where; 
Rect DragRect; 
long okay = TRUE; 


/* the result of FindWindow */ 


DoubleClicked = (Event.when - LastMouseUp < GetDblTimeC)); 
MousePosition = Event.where; 
Where = FindWindowCMousePosition, &WhichWindow); 


poo (Where) 


case inDesk: break; 

case inMenuBar : 
DoMenuCommand(MenuSe lect(&Event.where)); 
break; 


case inSysWindow: SystemClickC&Event, WhichWindow); 
break; 


case inContent: if (ClickIsInActiveWindowCWhichWindow2) 
í р елкы S SSD SSL 
reak, 


case inDrag:  DragRect = screenBits.bounds; 
DragWindow(WhichWindow,MousePosition, &DragRect); 
break; 


case inGrow: 
break; 


WDispatch(WhichWindow, GROW, NULL); 


case inGoAway: 
tion)) 


if (TrackGoAwayCWhichWindow, MousePosi- 


if С _OptionKeuDown(Event)) 
while CCWhichWindow = MyFrontWindow()) AND okay) 
( WDispatch(WhichW indow, CLOSE, kokay) ;) 
else WDispatch(WhichWindow, CLOSE, &okay); 
break; 
default: 
Oops(“\pUnknown Window Туре in MouseDown Handler”, 0, 
TRUE); 


break; 
) /* switch (FindWindow. .) */ 
[a oy 
/* DoMouseUp */ 


/*Set current time into LastMouseUp for Double Click */ 
/*Detection in DoMouseDown. x/ 
—— M MÓÓÓÓM—ÓÓÓMM—MM— х/ 
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void DoMouseUp(Event) 
EventRecordEvent; 


extern long LastMouseUp; 
LastMouseUp = Event.when; 


/* —— A A. Ф 


/* Boolean ClickIsInActiveWindow(ClickedWindow)*/ 
/*A quickie to select back windows if the’re clicked. */ 
k nF s Wa 


/ */ 
8def ine ItIsnt (!ItIs) 


Boolean ClickIsInActiveWindowCCl ickedWindow) 
ou. ClickedWindow; 


register Boolean ItIs; 
long type; 


ItIs = (ClickedWindow == FrontWindow()); 
if (ItIsnt) SelectWindow(Cl ickedWindow); 
return(ItIs); 


) 
/* —.a.—. —..ə—ə- ————— 7 х/ 


/* DO KEY DOWN x/ 
/*This function handles a keydown event. If command */ 


/*key is down its a menu command, otherwise dispatch it */ 
/* —————————— x/ 


void DoKeuDown(Event) 
EventRecordEvent; 


register char keu; 
key = Event.message & charCodeMask ; 


if (_CmdKeyDown(Event)) 
else if (MyFrontWindow()) 
ispa ten uk ront indent) KENDON MEL), 


ж ---------“/ 
/* DO UPDATE х / 


void DoUpdateCwP) 
register WindowPtr wP; 


GrafPtr PortSave; 


GetPortC&PortSave); 
SetPortCwP); 
BeginUpdate(wP); 
WDispatchCwP, UPDATE , NULL; 
EndUpdate(wP); 
SetPort(PortSave); 


/* ————————————— х/ 
[* DO ACTIVATE х / 
Жш LR 


void DoActivate(Event) 
EventRecordEvent; 


register WindowPtr ActivateWindow; 
register int Message = DEACTIVATE; 


TurnArrowOn(); 
ActivateWindow = (WindowPtr) Event.message; 


1f (Event.modif iers & activeFlag) 
/* Activate vs Deactivate */ 


SetPortCActivateWindow?; 
Message = ACTIVATE; 


WDispatchCActivateWindow,Message, NULL); 
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DoMenuCommand(MenuKeyCkey22; 


) 
Listing: WIND Draw.c 


[BRERAAEKERERARER ERA RA ERE ER ERE RK EEA ER ASKER EAA A AAA AA ERE / 


/* SOURCE CODE FILE */ 
[R¥RERKERRER ERASER ERA AA ERE KER ERE REE ХХХ AAA EE EE / 
/* 

х 209 File name: 5.1 DrawWindow.c 

* >>> Purpose: Methods for Rectangle Object 

х >>) Project:  PoopDrew Version 1 


ху)» Date: 2/20/89 
х >>> By: Adam Treister 
*/ 


[REREEEAREREREER ERE RAR ERK ER EKER ERE REAR KA КККК AAA EXE / 


/*For Your Information 1802 Hillside Rd. SB CA 93101 */ 
[ SXXXEXEOCOOOOOEOOOOOOOOOOOOEOEOEOOEOOOODOODOCDOOOOOOEOOOE EE / 


Sinclude “PoopDrawInc” 
void DrawOutlineCRect r,int curTool); 
МА struct 


-Std0bjectF ields 

ObjectHandle ` drawPanel; 
ControlHandle — vScrollBar,hScroliBar; 
Point сиг0гідіп; 


ObjectHandle doc;  /* info about files and printing */ 


) WindowDataRec,*WindowDataPtr,**WindowDataHandle; 


/***xx Public Functions ЖЖХЖЖЖАЖХЖЖАЖЖЖЖЖАЖЖХАЖЖЖАЖЖЖЖЖЖЖЖЖ / 


/* WindowPtr NewDrawWindow(void); */ 
/***x*x Private Functions ЖЖЖЖЖЖАХЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ / 


DrawWinDispatch(WindowDataHandle ObjectH, int message,LPtr 
ParmP); 

WindowPtr NewDrawWindow(void); 

private void Dispose(WindowPtr wP); 

private void MouseDown(WindowPtr wP); 

private void Grow(WindowPtr wP); 

private void KeuDown(WindowPtr wP); 

private void Update(WindowPtr wP); 

private void Activate(WindowPtr wP); 

private void DeActivate(WindowPtr wP); 

private WindowDataHandle GetWinData(WindowPtr wP); 


[***** Local Defines & Includes **xXrxxcnnoeeeneeoeonpepp/ 
Sdef ine UntitledWindowName" NpUnt i tled^ 


/ХЖЖЖЖЖХЖЖЖЖАХЖАЖЖАХЖАЖЖАЖЖАЖЖЖАЖЖЖАЖХХЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖ / 
DrawWinDispatchCObjectH,message,ParmP ) 

WindowDataHandle ObjectH; 

int message; 

LPtr ParmP; 


WindowPtr wP; 
wP = (*0bjectH)->port; 
switch (message) 


case CLOSE: 
case DISPOSE: Dispose(wP); break; 
case MOUSEDOWN:MouseDown(CwP ); break; 


case UPDATE: Update(wP); break; 
case ACTIVATE: — ActivateCwP); break; 
case DEACTIVATE: DeActivateCwP); break; 


case GROW: Grow(wP); break; 
default: DispatchCC*O0bjectH2- 
? drawPanel,message,ParmP); 
)) 
/* — k, х/ 
/* New Draw Window х/ 
/* —————F V. х/ 


WindowPtr NewDrawWindowC2 
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WindowPtr wP; 

Rect BoundsRect; 
WindowDataHandle WinData; 
extern Boolean DEBUG; 


BoundsRect = screenBits.bounds; 
BoundsRect.top += 40; 


WinData = .GetHandleToRecord(WindowDataRec); 

NullOutHandle(WinData?; 

wP = NewWindow (NULL, &BoundsRect, UntitledWindowName, 
true, documentProc, -1L,true, (long) WinData); 


SetPor t(wP); 
(*WinData)-?port = wP; 
(*WinData)->dispatch = DrawWinDispatch; 


NewCDRAWPANEL , WinData, &C*WinData)-? drawPane1); 
return (wP); 


) 

/* ---------------- ж} 

/* Dispose Document Window x/ 
/* ——————————— */ 


void DisposeCwP) 
WindowPtr wP; 


WindowDataHandle TheWindowData = GetWinDataCwP); 


DispatchCC*TheWindowData2-? drawPanel , DISPOSE, NULL); 
DisposeHandle(CTheWindowData); 
DisposeWindow(wP); 


/х -------------:/ 
void MouseDownCwP) 
por wP; 


short Par tCode; 

ControlHandlectr]H; 
extern EventRecord Event; 
register Point pt; 


pt = Event.where; 
GlobalToLocal(&pt); 
PartCode = FindControl(pt, wP, &ctr 1H); 
/*if (Par tCode) 
HandleScrollBars (wP,ctrlH,pt, PartCode); 
else 


*/( 
WindowDataHandle WinData = GetWinDataCwP); 
DispatchCC*WinData2-? drawPanel,MOUSEDOWN, NULL); 


) 
х-----“/ 
void GrowCwP) 

WindowPtr wP; 

( 


WindowDataHandle WinData; 
long newSize; 

Rect oldRect,growZone; 
extern EventRecord Event; 
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int newH ,newV ; 


WinData = GetWinDataCwP); 

growZone = screenBits.bounds; 

growZone. left = 108;growZone.top = 260; 

newSize = GrowWindow(wP Event . where, &growZone); 
if (!newSize ) return; 


newH = LoWord(newSize); пену = HiWord(newSize); 
SizeWindowCwP ,newH, newV , TRUE); 
DispatchCC*WinData2-? drewPanel,RESTZE, NULL); 
ClipRect(&wP->por tRect); 

EraseRect(&wP-> por tRect); 
InvalRect(&(CwP-> por tRect)); 


) 

/[* ——Ə—— Ü Ə — 3Á  .— .@nT */ 
/* Update х/ 
/* --------Ұ/ 


void Update(wP) 
WindowPtr wP; 
( 


WindowDataHandle WinData = GetWinDataCwP); 
Rect r; 


r = wP->portRect; 
ClipRect(&r ); 
DrawControlsCwP); 
scrolling */ 
DrawGrowIcon(wP); 
r.right -= ScrollBarWidth; r.bottom -= ScrollBarWidth; 
ClipRectC&r); 
DispatchCC*WinData2-? draewPane!, UPDATE, NULL); 


) 

/* 

x Activate 
* 


/* there are none, unless uou add 


*/ 
void Activate(wP) 
WindowPtr wP; 


/* activation of controls goes here */ 


/* 
x Deactivate 
х-----------------</ 


void DeActivate(wP) 
WindowPtr wP; 


/* deactivation of controls goes here */ 


/* ——ñ -  */ 

/* GetWindowDataHandle x / 

/*This get WindowDataHandle from the refCon field of */ 
/*the window passed to the function. */ 

% _——————— t) 


WindowDataHandle GetWinDataCwP) 
WindowPtr wP; 


return((WindowDataHandle) GetWRefCon(wP)); 
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Jórg's Folder 
C++ Overview 


“An Overview Of C++” 

MacHack '89 brought me not only a colorful set of screw- 
drivers from APDA, but also a new assignment: yours truly is 
supposed to run a tutorial column on C++. C++ is a very 
interesting programming language. Supposedly, the new Finder 
was written in it. Also, it exists on a couple of Unix systems. In 
fact, shopping for a Unix system, we recently met a representa- 
tive who assured us that C++ would be delivered with the system. 
Jordan Matthews, and other people from Apple, spoke very 
highly about C++ at the MacHack, and assured us that we would 
get our fingers on a pre-release of Apple’s C++ for MPW, 
supposedly to be delivered by the end of this year. 

As you might have guessed, Apple hasn’t sent us the pre- 
release yet, and I have yet to use a working C++ compiler. So far 
my only ‘hands-on’ experience is Bjarne Stroustrup’s book, The 
C++ Programming Language (Addison-Wesley 1987), which I 
highly recommend. 

The style of the book is rather terse, and you have to work 
your way through. A good example is that after the introduction, 
not much is said about ‘object-oriented’ programming, until you 
hit page 213: 

“A list specified in terms of pointers to a class can hold 
objects of any class derived from that class. That is, it may be 
heterogeneous. This is probably the single most important and 
useful aspect of derived classes, and it is essential in the style of 
programming presented in the following example. That style of 
programming is often called object based or object oriented; it 
relies on operations applied in a uniform manner to objects on 
heterogeneous lists.” 

So now you know what you’ve really done when you used 
MacApp... The fact that Stroustrup refers to object-oriented 
programming in this rather abstract way made me dig out an old 
introduction to Simula 67, which was the first language to 
introduce object-oriented concepts. There, too (the book dates 
from 1973) no reference is made to OOP as we know it today. All 
the important constructs - classes, instances, methods, overriding 
- are already there, and one could have implemented today’s 
programming style in Simula; only computers were much 
smaller, and most programs did not demand OOP concepts. 


The C++ Design 

Stroustrup’s team designed C++ for dealing with simulation 
problems not unlike those that Simula was developed for. 
However, C++ is a much broader concept than simply a set of 
‘object-oriented’ extensions to C; it is a redesign of the C 
language. To use another quotation from Stroustrup’s book, 
“C++ was designed to enable larger programs to be structured 
inarational way so that it would not be unreasonable for a single 
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person to deal with 25,000 lines of code" . To achieve such an 
ambitious goal, the most important point is to allow the user to 
extend the language to accommodate new ‘shorthand notations’ 
for things that have to be done over and over again. For instance, 
in a program that uses matrix algebra, given the 25-row by 35- 
column matrix C and 25-row by 15-column matrix B, 


A = ^B*C 
is much easier to read than 
matmul (A,transpose(B),C,15,25,35). 


To be able to use such a shorthand for matrix multiplication, 
we would need two features built into the language: a, data 
structures that carry additional information, such as row and 
column size for a matrix, but which is normally hidden to the 
user; and b, the capability to redefine operators - like ‘*’ or ‘4’ - 
depending on the context in which they are used. The latter 
feature would then cause a **' to behave differently depending on 
whether it is used to multiply two integers, reals, vectors or 
matrices. Some of this behavior is already built into most com- 
pilers: integer and real multiply generate different code. But this 
behavior cannot be modified. C++ allows you to modify your 
operators in any odd way. 


Classes 
Let'sassume we wanted to define an array structure, matrix, 
whose size is not defined at compile time and for which space will 


be dynamically allocated at run time. In C, one might write 
ча struct matrix 


int rows, cols; 
int *m; /* pointer to matrix data */ 


matrix a 
and then write an indexing function elem(i,j) which refers to 


the (i,j)th element of the matrix a by 
х(а.т + 2*(i*a.cols + ])). . . 
Of course, it would be much easier to simply define a two- 


dimensional array and write a[i][j], but let's stay with this 
definition for a while; unlike the usual array definition, this 
matrix is resizeable and space is allocated dynamically at run 
time. We would have to find a block of memory to hold the matrix 
data and put a pointer to it in m. 

When we access an array, we are often not interested in its 
actual dimensions, as long as the indices are not out of range. In 
C++ we can define the matrix type in such a way that only certain 
functions have access to information 'private' to the array (such 
as its dimensions), and all access to the array's data is done 
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through these access functions, called methods. Data structures 
that may carry private information are called classes in C++. 
(According to the manual, classes are ‘user-defined types’ - the 
most general definition that one might imagine!). A class is just 
like a struct in which some of the fields cannot be ‘seen from the 
outside’, and in which the interface to these private fields is 
defined through method declarations. The C++ class definition 
for the matrix type would look very similar to a struct declaration, 
with some additions. The syntax of the class declaration is: 


class matrix 


int rows, cols; 

int *m; /* pointer to matrix data */ 
public: 

int rowsize() ( return rows) 

int colsize() ( return cols } 

void set_sizeCint, int); 

int& elemCint, int); 

natrixCint, int); 

“matrix; 


matrix a 
Those of you who have had some experience with NEON 


[let’s make the point again that it is a shame that NEON has 
disappeared...] might recall that its class definition looked 
similar: 
‘class matrix «super object 
2 <indexed 
int rows 


int cols 
:M rowsize .... ;M 


‘class 
NEON , however, did not have the label public: for separat- 


ing the private and public parts of the class declaration. In NEON, 
all variables were private and all the methods were public. 

The C++ class declaration is similar to a C struct declaration, 
with the possibility to include functions and to hide parts of the 
declaration from the outside. The public functions in a class that 
constitute the interface to the outside world are called methods. 

There are two principal ways to define a method. One can 
write the method code inside the class declaration (as for rowsize 
and colsize in the example above), or one can just declare the 
method and write the method code later, as for set. size or elem. 
elem returns the reference to an integer that is the (1,J)th element 
of the matrix and might be defined as follows: 


int& matrix::elemCint i, int j) ( return mL[i*cols + j] }; 


There is a fundamental difference between methods defined 
inside and outside of a class declaration. The methods defined 
outside will be called through a subroutine call, while inside- 
defined methods are inline-expanded by the compiler. Writing 
a.rowsize will not generate a JSR to the function code, but code 
that will directly reference the hidden field a.row. However, any 
method that is defined outside a class declaration may also be 
defined as an inline method by prefixing it with the keyword 
inline: 


@ The Best of MacTutor, Vol. 5 


inline int& matrix::elemCint i, int j) ( return mLi*cols + 

) ); 
"s There are two more special methods in the class declaration 
which carry the name of the class, or respectively the class name 
prefixed with a tilde (~). These are the so-called constructor and 
destructor methods; they are called when a new object is declared 
(as in matrix a;) or deleted (when one leaves the block that the 
object was declared in). Constructors and destructors are impor- 
tant when heap space has to be allocated for an object (our matrix 
will need it) and deallocated when the object is no longer defined. 


Operators 
Our dynamically sized matrix might be defined in a slightly 
different way which allows to access the elements in the usual 
way, writing a[i][j] instead of a.elem(i,j). One first defines a one- 
dimensional array class (as in Stroustrup's book): 


class vector 


int* v; 
int sz; 
public: 
vectorCint); ~vector(); 
int size () ( return sz; } 
void set_sizeCint); 
int& operator []Cint?; 
int& elemCint i) ( return vti) ); 


and then builds the two-dimensional class on top of it: 


class matrix : vector 


vector*& mv; 
int rows, cols; 
public: 
matrixCint, int); "matrix; 
int rowsize () ( return rows; ) 
int colsize (С) ( return cols; ) 
void set_sizeCint, int); 
vector*& operator []Cint); 
int& elemCint i, int j) ( return mvlillj] ); 


7 hope this is approximately correct while I' m waiting for 
the C++ system to try this out and get ready for your embarrass- 
ing remarks). In the program, one would declare matrix a(10,20) 
and access the (ij)th element by writing a[i][j. The array 
indexing operator [] has been re-declared in the class declaration, 
and will now support checking of index bounds, if we wish so. 

The actual implementation of the operators has of course to 
be done separately. We would write 


int& vector::operator[)Cint i) ( /* body of code */ ) 
and 


vector*& matrix::operator[]Cint i) ( /* body of code */ ) 
to implement the new definitions. 


The matrix multiplication operator may now be defined 
easily. We write 


matrix operator*(matrixk a, matrix& b) 


matrix c(a.colsize,b.rowsize); 
1f Ca.rowsize != b.colsize) error “index mismatch"; 
for Cint i=1 ; i«a.colsize ; 1++) 

a Cint j=1 ; j«b.rowsize ; j**) 
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int sum = 0; 

for Cint k=1 ; k«a.rowsize ; k++) 
Sum = sum + a[il[k]*b[k)[j]; 

c[i][j)] = sum; 


; 
return с; 


А едін. I hope this would work in an actual example. It is not 
the most efficient way to program the matrix multiplication; the 
good way to do it would be using friend definitions. This concept 
is explained in Stroustrup’s book, and I’m going to come back to 
it in the next column, where I can supply some examples. 

The expression a*b, where aand b are of type matrix, would 
return a pointer to another object of class matrix, which contains 
the product of a and b. To make sense of the expression c = ^a*b, 
we would also have to define the transpose operator, ‘4’, and the 
assignment operator, ‘=’. I won't write these definitions down 
here; you might try to work them out, or better, test them if you 


have a C++ system available. 

Operator redefinition is one of the most important concepts 
of C++, since it makes the code much more readable. The 
redefinition of an existing operator (like +, *, etc.) is called 
operator overloading; when such a redefined operator is used, the 
compiler will automatically search the existing definitions to find 
one that works on the data types provided. Thus, even if one 
redefined * for matrices, integer and real multiplications would 
Still work as before. I have not found out yet whether dynamic 
binding is possible for operators by declaring them virtual (see 
below), but I’m sure ГЇЇ soon be able to test that. 


Class Hierarchies 
We have seen the syntax of a class definition which was 
derived from another class, class matrix : vector { }. If we define 
a derived class this way, none of the methods in the superclass 


A sample class definition 
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Object Pascal 


type 
TShape = 

Object (TObject) 
Next:  TShape; 
Prev:  TShape; 
boundRect: Rect; 
ShapeRgn: RgnHandle; 
procedure Create(theRect: Rect); 
procedure Track(oldRect, newRect: Rect); 
procedure Draw; 
procedure Erase; 
procedure Free; Override; 

end, 


TCircle = 
Object (TShape) 
procedure Create(theRect: Rect); Override; 
procedure Track(oldRect, newRect: Rect); 


Override; 
procedure Draw; Override; 
end; 


TShapeWindow = 

Object (TObject) 
HeadofList: TShape; 
TailofList: TShape; 
procedure Init; 
function NewShape(knd: integer): TShape; 
procedure Add(Shape: TShape; 

theRect: Rect); 

procedure SelectAndMove(thePoint: Point); 
procedure Delete(thePoint: Point); 
procedure Update; 
procedure Free; Override; 

end; 
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C++ 


class TShape 


TShape* Next, Prev; 
Rect boundRect; 
RgnHandle ShapeRgn; 


public: 
virtual void Create(rect *theRect); 
virtual void Track(rect *oldRect,*newRect); 
virtual void Draw(); 
virtual void Erase(); 
virtual void Free(); 


} 
class TCircle : public TShape 


{ 

public: 
virtual void Create(rect *theRect); 
virtual void Track(rect *oldRect,*newRect); 
virtual void Draw(); 


} 


class TShapeWindow 
{ 


TShape* HeadofList, TailofList; 


public: 
virtual void Init(); 
virtual TShape NewShape(int knd); 
virtual void Add(TShape “Shape; rect *TheRect); 
virtual void SelectAndMove(Point thePoint); 
virtual void Delete(Point thePoint); 
virtual void Update; 
virtual void Free; 
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will be accessible through an object of the subclass; all subclass 
methods have to be explicitly defined in the subclass declaration. 
If we write, on the other hand, class matrix : public vector { ), any 
method from class vector that is not redefined in class matrix is 
usable on objects of class matrix as well. This is the way we very 
often wish objects to behave; methods that are redefined in a 
subclass should override the superclass definition, but if an 
object does not ‘know’ about a method it should look for a 
definition higher up in the hierarchy. 

In a class hierarchy we should therefore be able to apply a 
method to an arbitrary object whose exact type is not known at 
compile time. If the object's type is known at compile time, the 
compiler will simply generate a JSR to the appropriate method 
code, passing arguments as required. This is known as early 
binding in object-oriented jargon. If the type is not known, we 
must check at run time what type of object is given the method 
call, and see whether the method is defined in the object's class 
declaration or somewhere higher up in the hierarchy. This is 
called late binding; a run time error message will be generated if 
the method can't be found for a particular object. 

Late binding is important if we have alistof objects to which 
the same method should be applied, for instance a list of shapes 
- rectangles, circles, polygons - to be drawn on a screen. If the list 
is Кері in an array shapelist{i], we could then simply write 


for Ciz1;i«N;i**) shapelist[il.draw; | | 

to draw all the objects. This is very similar to Object Pascal, 
where we would write analogously 

for i :=1 to N do shepelist[i].draw; 
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However, in Object Pascal late binding is always used when 
early binding can’t be applied. In C++, we have to tell the 
compiler that a method could be used for late binding by declar- 
ing it virtual: 

class TShape { 

TShape* Next, Prev; 
Rect boundRect; 
RgnHandle ShapeRgn; 
public: 
virtual void Create(rect *theRect); 
virtual void Track(rect *oldRect, *newRect); 
virtual void Draw(); 
virtual void Erase(); 
virtual void Free(); 


his is the generic definition of a shape for which methods 
for drawing, erasing, etc. exist, but may or may not be defined in 
the top class; they may be overridden in the descendant classes, 
and the actual binding may be known only at run time. The figure 
illustrates the definition of a class hierarchy of shapes in C++ and 
in Object Pascal. 

This more or less concludes my quick overview of the main 
characteristics of C++ (of course, all the features of C are still 
present in the language). Don't laugh at the mistakes that are 
probably still in the examples; this happens when one writes 
programs without a compiler. There are many details I haven't 
gone into here; we'll get to know them in the following columns, 
with corresponding examples. Forth friends, don't despair; 
you'll get your share soon again, too. 


22) 
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C Workshop 
Three Doodats 


[Lee Neuse started in the days you built them before pro- 
grammed them. He was lured away from IBM compatibles to the 
Mac in 1982 and been there ever since. Currently, he is working 
for Computer Science Corporation designing and implementing 
Mac software as part of CSC research. His Mousehole handle is 
"Noisy".] 


Three Doodats 

Doodat— a trivial problem guaranteed to make a program- 
mer's life miserable; fromthe expression "How did he do dat?" . 

It seems like every programmer, at one time or another, is 
faced with the same dilemma: wanting to use a feature in a 
program, but not wanting to spend the time to figure out the 
technique. For example, we all know that a Balanced B-Tree 
index is wonderfully efficient, but how many of us really want to 
sit down and write the code? One solution is to start reading back 
issues of MacTutor, hoping that some kind soul has already 
published useable source code. Another is to scour public 
domain software for an author willing to impart knowledge in 
exchange for a shareware donation. Either way, it's usually 
faster (and easier) to find and adapt someone else's code instead 
of doing it yourself. 

The purpose of *Doodats' is to provide generic solutions to 
the little problems, so the programmer can spend his or her time 
working on the big problems (like what the program does). 


Doodat #1 

Problem: how to determine if the user has tried to abort 
something by pressing the Cmd-'.' keys. EventAvail() returns 
only the first keystroke event in the queue, and the user may have 
pressed some other keys since the last keystroke event was read 
by the application. Either GetNextEvent() or WaitNextEvent() 
return all keystroke events, forcing the application to store them 
or ignore them (a Bad Thing). Moreover, if MultiFinder is 
running, calling any of these event-related traps may cause the 
application to be switched out, which could cause problems. 


Solution: Doodat #1 isaroutinecalledcheck abort(), which 
directly scans the ToolBox’s internal event queue for Cmd-’.’ 
abort events. 

The routine starts by setting a pointer to head of the event 
queue (stored in the system global EventQueue), then examining 
the next event in the queue. If the event is a Cmd-'.' event, it is 
removed by calling Dequeue(, and the ‘found’ flag set. If the 
pointer does not match the event queue tail, it is advanced to the 
nextevent, otherwise, the function returns. This technique solves 
all of the problems posed by normal event processing: 

1. Itdoesn’taffect any other keystroke events in the queue. 
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2. If the user has generated multiple aborts (by holding the 
keys down), it removes all of them. 
3. It does not call EventAvail() or WaitNextEvent(, so no 
chance of being switched in or out under MultiFinder. 
То use check abort(),call it from within any place where the 
user might want to abort. For example: 


for (page = 1; page < last page; page**) 


/* print a page */ 
if (check_abort()) 
break; 


/YEXXXXXXXX1X12X11F1XXXXXXXXXXXXXXXXXXX1XXX1XXXXXXXXXXX 
xx 


**¥check_abort()- Lightspeed C Version 
xx 


**This routine returns scans the low-level 
**event queue in search of a Cmd-’.’ key event 
**Each one found is removed from the event 

** queue. 


**Out: TRUE if Cmd-’.’ found, FALSE otherwise. 
xx 
*/ 


Воо1еап 
check_abor tC) 


EvQEIPtr eq_p; 
Boolean f found = false; 


/* start at head of internal queue */ 
eq-p = (EvQEIPtr)CEventQueue . qHead); 


while (true) 


if (Ceq p evtQWhat == keyDown || 
Ceq_p-revtQWhat == autoKey) && 
Ceq_p-evtQModifiers & cmdKey) && 
(кн & charCodeMask) == 


` 
~ 
“7 


/* remove the event from the queue */ 
DequeueCCQElemPtr)eq.p, &EventQueue); 
f_found = true; 


/* test for end of queue */ 
1f (eq-p == (EvQE]Ptr)EventQueue.qlail) 
break; 


/* continue with next queue entru */ 
eq-p = (EvQE] *)Ceq_p->qLink); 


return(f_found); 
) /* end of check_abort() */ 


Doodat #2 
Problem: Many windows contain items such as lines, icons, 
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pictures, or text strings that are there for decoration; these items 
don't change in appearance, and clicking on them has no effect. 
While the code to draw these items isrelatively simple, it is also 
very boring to write, and frequently quite lengthy. In addition, 
trying to figure out exactly which horizontal and vertical co- 
ordinates to use can be time-consuming and frustrating. 


Solution: Doodat #2 is an attempt to save time (and code!) 
by making ResEdit and the Resource Manager do most of the 
work. This involves a two-step approach: 

Step 1 is to use ResEdit (or any other Resource tool) to create 
a ‘DITL’ resource (Dialog Item List) that contains all of the items 
desired. ResEdit is particularly handy, as the items can be 
arranged visually within the window. The DITL resource may be 
created and edited normally, with all items being set to disabled. 
No Control or EditText items should be included (they will be 
ignored if you do), and the items may be in any order. The 
finished DITL resource is then included in the application’s 
resources for later use. 

Userltems in the item list are handled in one of two ways: 
either as a dividing line or as frame. If the horizontal or vertical 
co-ordinates are equal, i.e. the boundary rectangle is empty, it is 
drawn as a 50% gray line. If the rectangle is notempty, itis drawn 
as a black frame. 

Text items are drawn (left-justified) in whatever font the 
window's port is using when draw. ditl() is called. Different text 
characteristics could be supplied by reserving the first few 
characters of the text string...but that's for another time. 

Step 2 is to use the routine below called draw ditl() to 
actually read in and draw the items within the window. This 
routine accepts the ID number of a DITL resource, reads the 
resource into memory, then traverses the item list, drawing each 
item accordingly. For draw. ditl() to work properly, the DITL 
resource must be present in the application's resource fork (or in 
an open resource file), and the port set to the desired window. 

draw. ditl() uses the following definitions and structure: 


8def ine NIL ØL 


/* Test a pointer for validity */ 
8def ine VALID_-PTR(p) CClong)(p) && 
CClong)(p) k IL) == NIL) 


/* Test a handle for validity */ 
$Sdef ine VALID .HNOLCh) CVALID.PTRCh2 && 
VALID.PTRCClong2C*Ch2) & OxQQFFFFFF 2) 


eer: struct 


Handle hndl; 
Rect frame; 
unsigned char type; 
unsigned char length; 
short data[]; 

) ditl_list; 


/YFXX32XXX1XXXXXXXXXX1X1X51XXXXXXXXXXXXXXXXXXXXXXXXXKX 
x* 


**draw.dit1C)- Lightspeed C Version 
xx 


X*This routine reads іп and draws the items in a 
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**Dialog Item List (DITL) resource. 
xx 


**In: resource id of DITL 
xx 


**¥Qut: N/A 
xx 


*/ 

void 

draw_ditlCditl_id) 

short ditl_id; 

Handle ditl.h; 

ditl list *ditl. p; 

PenState — save реп); 

short d_type, offset, num items; 


ditl.h = GetResource(‘DITL’, ditl_id); 
1f (ResError() != noErr || !VALID.HNDLCditl. h2) 
return; 


HLockCdit].h2; 

/* don’t change pen behind the window’s back */ 
GetPenState(&save. pen); 

PenNormal(); 

/* get the number of items in list */ 

num_items = *((short *)(*dit]_h)) + 1; 

/* set pointer to first item in list */ 

ditl.p = Cditl_list *)X(*dit]_h) + sizeofCshort2); 
while Cnum_items—) 


( 
/* mask out the item disabled bit */ 
mm (9141_р-› type & Ox7F) 


case statText: 

TextBoxCCchar. *)ditl_p->data, 
ditl_p-> length, &(ditl_p-> frame), 
teJustLef t); 

break; 


case iconItem: 
ditl-p->hnd] = 
GetIconCdit]l.p-»data[01); 
if (VALID. HNDLCdit]l p-»hndl2) 


( 

PlotIconC&Cditl p-»frame), 
ditl_p-»hnd1); 

ReleaseResource(dit}_p->hAnd1); 

) 


break; 


case picltem: 
ditl.p-—hndl = GetResource( ‘PICT’, 
ditl_p->datal@]); 
sn n s due 


DrawPicture((PicHandle)ditl1_p-hndl, 
&Cditl_p->frame)); 
ыы ады 


break; 


case userItem: 
if (EmptyRectC&Cditl.p-frame))) 


PenPatCgray); 

MoveToCditl p-»frame.left, 
ditl_p->frame.top); 

LineToCditl_p->frame.right, 
ditl_p-> frame bottom); 

oes 


else 
FrameRect(&(ditl_p->frame)); 
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break; 


/* force offset to a word (even) boundaru */ 
if (Coffset = ditl. p length) & 1) 
offset++; 
/* advance pointer to next item */ 
ditl.p = (ditl_list *)X(char *)ditl_p + 
sizeof(ditl_list) + offset); 


HUnlockCdi t1. h2; 
ReleaseResource(dit].h); 

/* restore pen to original condition */ 
SetPenState(&save pen); 

) /* end of draw_dit1() */ 


Doodat #3 
Problem: Sooner or later, an application is going to need to 
access a data file of some sort, with fixed-length or variable- 
length records, keys, and so forth. Using the Resource Manager 
asa Poor Man's Database is a Bad Thing according to Apple, and 
noteveryone can afford (or write) a full ISAM (Indexed Sequen- 
tial Access Method) utility. 


Solution: Doodat #3, which includes some primitive (but 
useful) indexing routines. If used properly, they can be used for 
indexing files, arrays, or be used for look-up tables, etc. 

All of the routines are based on the idea of a simple index, 
made up of 1-л index entries. Each index entry is a key value and 
it’s associated data value, and is defined in the index entry 
structure below. The key and data values are always handled in 
pairs: for any given key, there is only one data value (provided 
itexists). Duplicate keys are not allowed, and both key and data 
values are limited to numeric values. What the key and data 
values actually represent depends on the application, an obvious 
example would be relating a part number to an offset into a file. 

Several different indices can be manipulated using the same 
routines, it is the application's responsibility to determine which 
index to use. If the indexes are small and/or few in number, they 
could be manually rebuilt each time the application is executed. 
Alternately, they could be saved between sessions, either as data 
files, or as resources: all that is needed the memory block 
referenced by the index handle (use GetHandleSize() to find it’s 
size). An elegant solution would be to save any or all data file 
indices as resources in the data file's resource fork, but that would 
limit the index size to 32K. 

Adding a new key to an index (or updating an existing key) 
is done by the db insert, key() function: a pointer to the index 
handle, a key value, and the data value associated with the key are 
all passed as parameters. If the index handle is NIL, a new handle 
is allocated, otherwise, the index is expanded by one index entry, 
and the new key added to the index in ascending order. If the key 
value already exists in the index, the data value is updated with 
the new value. 

Once an index has keys inserted into it, db get key() can be 
used to search the index for a given key value. The routine 
expects an index handle and a key value, then performs a binary 
search on the index. If the key value is found, the data value 
associated with the key is returned, otherwise -1 is returned to 
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signal failure. 

There may be times when it is necessary to find a key's 
location in the index, thus db get seq key() accepts an index 
handle and an entry number, then returns the key value found at 
that entry. Once again, -1 is returned to signal failure if the entry 
number is less than 1 or greater than the number of keys. This 
routine can be used to sequentially read through an index (in 
ascending order), using the following code: 


long w_key, key-value; 


w_key = IL; 
“е (true) 


key-value = db_get_seq_key(my_index, w-keu++); 
1f (key-value == -1L) 
break; 


my-data = db_get_key(my_index, key-value); 
/* 


**process my_data here 
%/ 
) 


Some possible extensions to these гошіпев include modify- 
ing them to store a character pointer as the key, providing non- 
numeric keys. For small indexes, the entire data record could be 
embedded as part of the index_entry structure, and a pointer to 
the structure returned by db, get. key(). 

The routines db get key(), db get seq key(), and 
db insert, key() all utilize the following definitions and struc- 
ture: 


Sdef ine NIL ØL 

/* Test a pointer for validity */ 

8def ine VALID.PTRCp) (C(long)(p) && 
CClong)(p) & 1L) == NIL) 


/* Test a handle for validity */ 
8def ine VALID HNDLCh) CVALID.PTRCh) && 
VALID-PTRCClong)C*Ch2) & Ox@OFFFFFF )) 


ы struct 


unsigned long keu; 
unsigned long data; 
) index_entru; 


/YKYXXXKXXXXXXXXKXX1XKXXXXXXXXX1XXXXXXX1XXXXXXF1XF1X1XXXXEK 
xx 


**db. get keyC) 
жж 


**This routine performs а binary search оп а 
**list of index entries 

хх 

**In: index hndl Handle to index 

x target key value to find 

xx 


**0Out: -1 if NOT found, data value otherwise 
xx 


*/ 

1ong 

db_get_keu(index_hnd], target) 
Handle index_hnd1; 


oo long target; 
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register index_entry*i_ptr; 
register long mid, low, high; 


if CVALID_HNDL(C index_hnd1)) 


( 

low = 1L; 

high = GetHandleSize(index_hnd]) / 
sizeof Cindex entry); 


while (low <= high) 


/* calculate the mid point of list */ 
mid = (Clow + high) >>) 1) - 1; 
i-ptr = *index_hndl + (mid * 

sizeof Cindex_entry)); 


1f Ci_ptr->key > target) 
/* too big, so look in lower half */ 
high = mid; 
else if Сі_ріг-› кеу < target) 
/* too small, so look in upper half */ 
low = mid + 2; 
else 
/* hmmm, guess we found it.. */ 
return(i_ptr->data); 


return(- 1); 
) /* end of db_get_key() */ 


/^*®**ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
x* 


x*db_get_seq_keu() 
xx 


**This routine reads a list of index entries, 
**returning a key based on a sequential number 
xx 

X*In: index.hndl Handle to index 

хх key_num key number to return 

xx 


*xQut: -1 if NOT found, key value otherwise 
xx 


х/ 


long db_get_seq_keu(index_hndl, Кеу лит) 
Handle index_hndl; 
oo key_num; 


index entry*i. ptr; 
long result = -1L; 
short num. keys; 


if CVALID-HNDLCindex-hnd1) 


/* count number of keys in index */ 
num keys = GetHandleSizeCindex_hndl) / 
sizeof Cindex entry); 
1f pum < num keys) 


/* calculate offset into the index */ 
i-ptr = *index hndl + (keu-num * 
sizeof Cindex_entry)); 
ыы = i ptr key; 


) 


return(result); 
) /* end of db_get_seq_key() */ 


/YXYXXX1X1XXX1XXXX1XXXXXXXXXXXXXX1XXXKXKKXXXKXKEXKXKXXXEX 
xx 


** db. insert keyC) 
xx 


**This routine inserts a key into an index. 
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xx 

**In: index_hndl Handle to index 

** target key value to insert 
xx data data value associated 
хх with the Кеу 

xx 

xx Out: N/A 

x/ 


void 

db. insert keyCindex hndl, target, data) 
Handle — *index-hndl; 

long target; 

(2 data; 


register index_entru*i_ptr, *n_ptr; 
register long nid, low, high, i_size; 


/* empty list is special case! */ 
if CIVALID-.HNDLC* index hndl2) 


/* allocate new handle */ 
*index hndl = NewHandle(sizeof Cindex епігу22; 
Ссіпдех. entry *)(**index_hnd1))-»key = target; 
шаны; *)(**index_hnd1))-»data = data; 


else 


low = IL; 
high = i.size = GetHandleSizeC*index hndl) / 
sizeof Cindex_entry); 


Тт? (low <= high) 


/* calculate the mid point of list */ 
mid = (Clow + high) >> 1) - 1; 
i-ptr = *index_hndl + (mid * 

sizeof Cindex_entry)); 


if Ci_ptr->key > target) 
/* too big, so look in lower half */ 
high = mid; 
else if Ci-ptr->key < target) 
/* too small, so look in upper half */ 
low = mid + 2; 
else 
/* found it, so store new key value */ 
i_ptr->data = data; 


/* extend handle by size of one entry*/ 
SetHandleSize(*index hndl, Ci-size + 1) * 
sizeof Cindex_entry)); 
/* test for memory error here */ 
n_ptr = i_ptr = **index_hndl] + (mid * 
sizeof Cindex_entry)); 
memcpy(**n.ptr, i.ptr, Ci.size - mid) * 
sizeof Cindex_entry)); 
/* do we insert as right or left? */ 
if Ci_ptr->key < target) 
i-ptr = n.ptr; 
/* and move in the new key and data value */ 
i_ptr->key = target; 
i_ptr->data = data; 


) 
) /* end of db insert keyO) */ 


145 


System Sleuthing 
World CDEV Investigated 


Sleuthing the Map Cdev 
Martin Minow and Mike Carleton 

(Martin Minow is a Principal Engineer at Digital Equipment 
Corporation. Originally a speech major (later a linguist), he 
decided he might need a “real” job someday, so he took the last 
programming course given for the Illiac I computer in 1962. 
When his graduate study grant ran out, he joined Digital Equip- 
ment Corporation in 1972, where he has held positions in 
software support and speech research and development, eventu- 
ally working on the DECtalk speech synthesizer. He is currently 
a Principal Engineer in the mid-range system’s advanced devel- 
opment group. In his spare time, he runs marathons (slowly), and 
orienteers (even more slowly). 

Mike Carleton received his BSEE in 1981. He first worked 
on special purpose compiler systems used to test the black boxes 
in fighter aircraft. After joining Digital Equipment Corporation 
in 1984 he supported the TOPS-10/20 COBOL compiler. Later 
he joined up as the system engineer for the VAX Supercomputer 
Gateway product and worked hand in hand with Cray Research 
engineers to make their two systems talk to each other. Currently, 
he is a Senior Software Engineer at Digital Equipment Corpora- 
tion.] 


System 6.0 includes an unexpected gimmick—a control 
panel program that displays a world map and allows you to select 
your location and time zone. The system is distributed with about 
80 large cities already defined, and itis very easy to add your own 
location. However, there doesn't appear to be any published way 
to extract the information for your own applications. 

With a little poking around, we were able to decipher the 
internal information and think that other MacTutor readers might 
find it useful. By using the code in the following program, your 
phase of the moon program (or program to determine sunrise and 
sunset times) need not ask the user to specify the system's 
location. 

The program has only been tested on Mac SE's and Mac II's 
under System 6.0. At its heart is a subroutine to read data from 
the clock parameter ram. 

The data is returned in three longwords with the following 
format (the actual numbers locate a suburb of Boston) found in 
figure 1. 

Latitude and longitude are stored as a fraction of the circle. 
Youcan think of latitude and longitude either as signed quantities 
ranging from -.5 to 4.5, or as unsigned quantities ranging from 0 
to 1. The right method depends on your program's needs. For 
example, since people don't think of Boston (71?05' West) as 
288°55' East, a program that displays the location would proba- 
bly treat the numbers as signed, as shown in the example 
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Martin Minow 
Mike Carleton 
Arlington, MA 
Volume 5, Number 9 


42924" North 


71°14' West 
S:00 West 
Parameter Layout 
Figure 1 


program. 

Time is stored as the number of seconds offset from UTC 
(GMT) in the low three bytes of the third longword. The high 
byte is zero. When the 24-bit value is sign-extended, it will be 
positive for offsets East of UTC, and negative for Western 
offsets. 


Sleuthing the Parameter RAM 

The parameter RAM is a block of memory in the clock chip 
that is kept alive by a battery when the computer is turned off. It 
was included in the Macintosh to store a small amount of 
environmental information that should not change when the 
system is booted from a different floppy. The MAP CDEV data 
is stored here because Apple wanted your Mac to know that it is 
located in Boston even if it was booted from a disk created in 
Cupertino. 

The classic Macintosh has 20 bytes of parameter memory. 
The contents are copied to low memory when the system is 
booted and you should access it by referencing the SysParam 
block as discussed in Inside Macintosh, volume II, chapter 13. 
When Apple introduced the Mac SE and Mac II, they used aclock 
chip with 256 bytes of memory. Since only the 20 bytes of the 
classic Mac are copied to system memory, we had to find a way 
to access the rest of the information. 

The read param ram() function below is the C-language 
interface to the undocumented ReadXPRam trap that we found 
tucked away in the 256 KByte ROM. This routine can read any 
part (or all) of the 256 byte parameter RAM. It takes three 
parameters: a pointer to a buffer, an offset from the start of the 
parameter ram, and a count of bytes to copy to your program’s 
buffer. It returns an OSErr code which read_param_ram() then 
returns to your program. 
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Finally, we would remind you that you shouldn't assume 
that Apple will keep this information in the same place or format 
in future system releases. 

In a recently-published document, Apple described 
ScriptManager 2.0 which contains support routines to allow 
reading and writing the Map information. As we show in the 
article, the information is stored in three longwords (Fract 
format) with the following format: 


struct MachineLocation ( 
Fract latitude; 
Fract longitude; 
union ( 
char disDelta; 
/* Signed byte: daylight savings time delta */ 
long gmtDelta; 
) gmtF lags; 
); 


Тһе ScriptManager defines two functions to read and write 
the Map data: 


pascal void ReadLocation(MachineLocation *loc); 
pascal void WriteLocation(const MachineLocation *loc); 


("const" is a keyword that was added to the Draft Ansi C 
Standard: it indicates that the parameter will not be changed by 
the function. You can omit it without harm.) 

Latitude and longitude are stored as fractions of a great 
circle: see our code for details. The low-order three bytes of the 
third word (gmtFlags.gmtDelta & OxOOFFFFFF) contain the 
number of seconds the timezone is East of the prime meridian. 
Note that the high byte must be masked off and the high-bit 
propogated to get the timezone offset: this is shown in our 
program. The high byte is marked “reserved” but seems to be a 
repository for a Daylight Savings Time offset. 

I don’t know when the ReadLocation (and WriteLocation) 
functions will be available: they are not present in the current 
release of Think C. Until that time, our sample program should 
be usable, but the cautious program will switch to an approved 
interface as soon as possible. 

/ 
This is a simple program to demonstrate 
extracting information from the Macintosh 
parameter RAM and displaying the current 
latitude, longitude, and time-zone offset. 
Note that the format and manner of storage 
of this data have not been published by 
Apple. 

This program is copyright @ 1988, 1989 

by MacTutor magazine. You may incorpor- 
ate portions of this program in your 


applications without restriction. 
Compile using Think C, V3.0. 


е зе зе зе ж е 3* зе ияж x x x »* * kk 


Written by Martin Minow and Mike Carleton 
/ 


8include«stdio.h» 

/* 

* Define the "Read parameter гат” trap and 
* the offset in the parameter ram where the 


€ The Best of MacTutor, Vol. 5 


* map is stored. This information doesn't 


* seem to be written down anywhere. 
*/ 
Sdefine _ReadXPRam 0xA051 
Sdefine Map_Offset 0хЕ4 /* Ram offset */ 


~“ 
ж 


This structure defines the location 
current]u set bu the Map Cdev. 


specifuing the fraction of the circle: 
1 degree East == 0x000308B9 
1 degree West == @xFFFCF747 

All values are possible for longitude, 


are used. The value is the number of 


є € 93 м и X x и % э м мж 


West negative. 

*/ 
Sifdef Use_Script_Manager 
Sinclude <ScriptMgr .h» 


typedef struct ( 
Fract latitude; 
Fract longitude; 
union ( 
char disDelta; 
long gmtDel ta; 
) gmtF lags; 
} MachineLocation; 


MachineLocation info; 


pascal voidReadLocation(MachineLocation *); 


telse 

typedef struct ( 
long latitude; 
long longitude; 
long timezone; 

} MapDatum; 


MapDatum info; 
Sendif 


void main(void); 

void  dms(long, char *, char *); 

void  hmsClong, char Ж): 

05Егг read_paramsram(void ж, int, int); 


void printf(char *, ...); 
int fgetc(FILE *); 


void 
mainc) 
( 


OSErr Status; 
/* 


* This is a test for divide rounding. 
х It should yield 180900700" W. 
*/ 


dms(0x80000000L, "Test", "EW^); 
x 


* Loop through here until the user types ‘q’ - this lets 


Latitude and longitude are long integers 


while latitude is constrained to + 90°. 
Only the low-order three bytes of timezone 


seconds offset from UTC, East is positive, 


you run the Map Cdev at the same time to see how location and 


timezone changes affect the data. 
х/ 
do ( 


8ifdef Use Script Manager 
ReadLocation(&info); 
dmsCinfo. latitude, “Latitude”, “NS”); 


dmsC info. longitude, “Longitude”, “EW”); 


hmsCinfo.gmtFlags.gmtDelta, “Zone”); 
Selse 
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status = read param _ram(kinfo, 
Map-Offset, sizeof (MapDatum)); 
if (status != noErr) 
printf("Error %$dVn?, status); 
dmsCinfo. latitude, “Latitude”, "NS^)5; 
dmsC info. longitude, “Longitude”, “EW”); 
hnsCinfo.timezone, “Zone” ); 
Sendif 
) while (getchar() != ‘q’); 


/* 

* Convert to degrees/minutes/seconds. 
x/ 

void 

dns(raw value, what, zone) 

long raw. value; 

char *what; 

char *zone; 


register longvalue; 
register longdegree, minute, second; 
int west; 


static longone degree 
static longone_minute 
static longone.second 


(0х800000001 / 1801); 
(0x80000000L / (1801 х 601)); 
(0x800000001 / (1801 х 601 * 6012); 


value = raw_value; 
degree = value / one_degree; 
= (degree * one_degree); 
= value / one_minute; 
value -= (minute * one-minute); 


if ((west = (raw_value < 0))) { 


degree = (-degree); 
minute = (-minute); 
second = (-second); 


) 
printfC^2081x: 31890214 '%0214\* $c $sWn", 
raw value, degree, minute, second, zone[west], what); 


/* in Ай, and trap to ROM. _ReadXPRam returns noErr on success 
* Convert time to hours:minutes:seconds. and prInitErr on failure. 
x/ */ 
void asm { 
hmsCtimezone, what) move.w — count,D0 
long timezone; swap 00 
char *what; move.w start,D@ 
movea. | address, A2 
register longvalue; dc.w _ReadXPRam 
register longhour, minute, second; return - 
int west; ) p 
¿mapy 
) 
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static longone_hour = (6@L * 60L); 
static longone_minute = (60L); 


if Ctimezone & 0хҒҒ000000) ( 
printf(^timezone high byte %881x\n’, 
timezone); 
timezone &- Ox@OFFFFFF; 


/* 
* Propogate sign bit from bit 23 to bit 31 if West of UTC. 
*/ 
if (Ctimezone & 0х00800000) !- 0) 
timezone |= 0хҒҒ000000; 


value = timezone; 
hour = value / опе hour; 
value -= (hour * опе hour); 


minute = value / one. minute; 
value -= (minute * one. minute); 
second = value; 
if (Cwest = (timezone < 0))) ( 
hour = (-һоуг); 
minute = (-minute); 
second = (-second); 


printfC^2081x: 231d.2021d.2021d $c s\n’, 
timezone, hour, minute, second, "EW^"[west], what); 


/* 

* Read data from the clock parameter ram. The start parame- 
ter specifies the offset within the parameter ram where the 
read is to start. The count parameter specifies the number of 
bytes to read. 

*/ 
05Егг 
read_param_ramCaddress, start, count) 
void *address; /* Result loc*/ 


int start;  /* Ram start */ 
int count;  /* Read size */ 
/* 


* Put the count into the high word of 00, the pRRAM start 
address into the low word of 00, the Macintosh memory address 


Advanced Mac'ing 


Dot Matrix Printer Driver 


A Dot-Matrix Graphics Printer Driver 

Thisarticle describesa Macintosh printer driver foruse with 
a Tandy DMP-110 dot-matrix printer. The printer resource file 
is written to be device-dependent, but it can serve as a skeleton 
for creating printer files for other devices. The routines to 
translate QuickDraw BitMaps to DMP-110 graphics codes are 
localized, so that one would only have to rewrite a few routines 
to create a driver for another dot-matrix printer. The printing 
code is in a combination of assembler and C, and may be 
compiled with either MPW C and Asm, v 2.0.2 or Aztec cc and 
as, v 3.6c. All files necessary for compilation with either system 
are included, but the Aztec-specific files assume that you have 
the MPW Shell, MPW Make, and Rez. 

This driver implements the Print Manager high level print- 
ing calls, so that any Macintosh application which uses them can 
print on this printer. I attempt to emulate as closely as possible 
the ImageWriter driver in high-resolution (Best) mode, subject to 
the physical limitations of the printer. I provide portrait mode 
printing only, with a choice of scaling factors. Anyone who has 
taken a college math course will recognize the spirit of the 
following sentence: “I leave Landscape Mode printing as an 
exercise for the reader.” The driver also implements two low- 
level procedures to dump BitMaps to the printer, so that com- 
mand-shift-4 will work. 

The printer file is missing some features which can be found 
in Apple printer files. It does not implement the driver’s low- 
level BitMap proc or, indeed, any of the low level printing calls. 
Users of most applications will not notice this lack, since few 
applications use low level printing. It does not participate in text 
positioning and measuring or “line layout” as do Apple printer 
drivers. This means that although the printer file works well with 
screen fonts like Geneva and New York, LaserWriter fonts like 
Times and Courier sometimes give it problems. This is a feature 
which should be added, but it might take lots of code to do it right. 

The code used in the printer file does not access low memory 
globals, except as these are used in library routines. It does not 
use any development-system-specific tricks to obtain “global” 
variables for the driveror for any of the code resources used in the 
driver. It does not use hard-coded numbers for the ioRefNum of 
the serial port or of the printer driver, but rather opens drivers by 
name. Any access to the Print Manager, e.g. to set or detect a 
printer error condition, is done through glue routines or through 
the PrGlue trap. In view of these precautions, the code should be 
fully capable of being used with other development systems, and 
should be compatible with future releases of Apple System 
Software, providing Apple does not change the interface to 
printer files too much. 
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Earle Horton 
Hanover, NH 


DMP-110 Volume 5, Number 10 


The Printer File: 

This section describes the resources you must create in order 
to implement a driver of this type. The structure of a printer 
resource file was described in my previous article (MacTutor 
Volume 3, Number 11 and 12), so I will give the resource list 
here, arranged roughly by function, and only describe the con- 
tents briefly. (You can geta list like this using MPW Rezdet with 
the “-I command line option.) 


DMP-110 Resource List 


‘PDEF’ (Ø, Purgeable, Locked) # Code resources 
‘PDEF’ (4, “Dialogs”, Purgeable, Locked) 

‘PACK’ (-4096, “Chooser Device”, Purgeable, Locked) 
‘DRVR’ (-8192, *.XPrint^, Purgeable, Locked) 


“НЕХА” (-8192, "Printer Settings") 8 Port settings 


^[CN8^ (128, "DMP-110^) 
‘FREF’ (128) 

‘Dmp1’ (02 

‘BNDL’ (128) 


# Bundle 


"STR ' (-4092, “Right Button”) # For device package 
‘STR ' (-4093, “Left Button”) 

‘STR ° (-4091, “List label’) 

‘STR®’ (-4080, "Baud Rates”) 


"DITL' €-8191, “Job dialog tempplate”) 8 Style and Job 
dialogs 

‘DITL’ (-8192, “Style Dialog Template”) 

"DLOG^ (-8191, "Job Dialog”) 

"DLOG^ (-8192, “Style Dialog”) 


‘DLOG’ (-8190, "Next Page Вох”28 Miscellaneous 

‘DITL’ С-8 190, "Next Page Template”) ® dialogs and alerts 
"ALRT^ (-4079, "Sys4lAlert^) 

'DITL^ (-4079, *Sys41 Items”) 

‘ALRT’ (-4078, “ATalk is on!^) 

‘DITL’ €-4078, “АТа1к Items”) 

“ICON” (-4080, *DMP-110^) 


‘PREC’ (0, “Default Scale”) ® Print Records 
‘PREC’ (1, “Last Used Print Record”) 

‘PREC’ (2, "Shrink To Fit”) 

‘PREC’ (3, “Exact BitMap’) 


‘PREC’ (4, “Compatible” ) 


Four code resources are included. The printer driver 
(DRVR' -8192) and the dialog code (‘PDEF’ 4) are necessary to 
any printer resource file. At least one type of printing code 
(‘PDEF’ 0, here) is also necessary. The Chooser device package, 
(PACK' -4096) is necessary if we wish to have adjustable 
settings which are not logically part of the standard Style and Job 
dialogs. A “НЕХА” resource is included to save global settings; 
it is quite small. 

The Chooser device package uses both buttons, and displays 


149 


a string list of baud rate names in the Chooser’s list box. 

Four unique Print Record resources (‘PREC’) are used here, 
for four different printing styles. The same paper style is used in 
all four of them, but different scaling methods are used to obtain 
different printing effects. ‘PREC’ number 1 is used to store the 
last-used Print Record. 

The rest of the resources are used in the dialogs and alerts, 
and the Bundle-associated information is used by the Chooser to 
display our printer file. Informative alerts and dialogs are 
provided for sheet feeding and for problem situations. An ICON 
resource containing the printer file icon is used to assure user 
identification of exactly who is putting up an alert. Alerts which 
might be displayed by the Chooser device package are given 
resource numbers which are in the legal range for the device 
package to use. Other Alerts and Dialog resources are given 
resource numbers belonging to ‘PDEF’ #0. 


Cast of Characters: 
The Files 
This section shows the source files used to build the printer 
resource file, and the icon used by my printer file. 


17 items 1 ,256K in disk 8,5Ө4К available 
O) 


AZF inalr  AZGlue.asm AZHeaders.c AZMakefile 


a) 3j 


MPwFinalr  MP'wGlue.a MPWMakefile compath ОМР-110Һ 


dmp-110 


` 
B Common 


Шәке [B] 


DMP-110 Source Files end Printer File 


The files with the ‘Manx’ icon (“Z”) are used in creating the 
Aztec version of the printer file. The files with the MPW icon are 
for use with MPW C and Asm. The *Anonymous" files are for 
use with both systems. All are ‘TEXT’ files, with the exception 
of theprinterfile. Intermediate object, code and resource files are 
not shown. 

Different source files exist for Aztec and for MPW for a 
number of reasons. Assembler syntax is different, so each system 
has its own “Glue” source file. Compiler and linker options, as 
well as mechanics of making the project, differ. Thus the two 
Makefiles. (Both use MPW Make, however.) The “...Final.r” 
file is different between the two systems because the Aztec linker 
refuses to create a non-' CODE' resource with ID zero, and it is 
more convenient to change this ID using the resource compiler. 
Finally, the file “AZHeaders.c” is used to create a precompiled 
header file for the Aztec C compiler. MPW C v 2.0.2 has no such 

feature. | 

Common files include two C language header files, a re- 
source definition file, and four C language source files. The bulk 
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of the project code is in C; the assembler files provide necessary 
headers for code resources, as discussed in the 1987 article. 

This project uses the Pascal interface to all ToolBox rou- 
tines, as introduced in MPW C, version 2, and as described in 
Appendix H of the MPW C manual. An esthetic problem with 
this approach is that it requires the programmer to type in certain 
routine names in UPPER-CASE, e.g. GETNAMEDRE- 
ЅООВСЕ() for GetNamedResource(). The header file 
“compat.h” uses preprocessor macros to hide this ugliness. 
When using Aztec C, including “-D_INLINE” on the C compiler 
command line and using “sys2:lib:azc.lib” accomplishes the 
same thing. All ToolBox and Operating System calls used in this 
printer driver use parameters as described in Inside Macintosh as 
a result. Points are passed by value, unless they are listed as 
“VAR” parameters in IM. Strings are always Pascal strings. The 
MPW Pascal style interface does not appear to include all the List 
Manager calls, but this is taken care of in the C source files rather 
than in the header file. Perhaps MPW 3.0 high-level languages 
will have a uniform programming interface for all IM calls. 

The C code as supplied can use either “PrintTraps.h” or 
"Printing.h" to define Print Manager calls which are used. For 
compatibility with systems older than 4.1, define 
BACKWARD COMPATIBLE in “dmp-110.h” so that 
“Printing.h” gets used. Use of the calls in “PrintTraps.h” results 
in smaller code. Use of “Printing.h” assures compatibility with 
older systems. For a driver for your own use, then, the newer 
header file is appropriate if you are running all your Macs with 
System 4.1 or newer. For distribution, the older header file is 
probably better. 

The header file “DMP-110.h” is the current version of 
"Daisy.h" from the 1987 article. It defines constants and 
typedefs which are shared between the various code resources. It 
gets smaller each time I work on itas the code moves closer to the 
point where the various code resources can be independent of 
each other. 

The main resource definition file, “DMP-110.rsrc.r,” is Rez 
source for all the non-code resources used in the printer file. If 
you are planning on using Aztec C or another system to build a 
printer file based on this one, and don't have MPW Shell, then 
you have to convert this file, or get the source disk and decompile 
the resources in the printer file. 

This article includes Aztec listings, but all files in the folder 
picture will be included in the source disk. 

The table entitled “DMP-110 Files Listing" shows all the 
files which exist in the project folder after a successful “buildpro- 
gram dmp-110" using the MPW language tools. 


DMP-110 Files Listing 


Name Crtr Type 
AZFinal.r Manx TEXT 
AZGiue.asm Manx TEXT 
AZHeaders.c Manx TEXT 
AZMakef ile Manx TEXT 
compat .h 2222 TEXT 
DMP- 110 Отр 1 PRER 
DMP- 110 .h 222? TEXT 


DMP- 110 .rsrc RSED rsrc 
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DMP-110.rsrc.r ???? TEXT 


Makefile MPS TEXT 
MPWFinal.r MPS TEXT 
MPWGlue.a MPS TEXT 
MPWGlue.a.o MPS OBJ 

MPWMakef ile MPS TEXT 
PACK RSED rsrc 
PACK.c 29222 TEXT 
pack.c.o MPS OBJ 

PDEF0 RSED rsrc 
PDEF0.c 2222 TEXT 
PDEF0.c.o MPS OBJ 

PDEF4 RSED rsrc 
pdef4.c 222? TEXT 
PDEF4.c.o MPS OBJ 

PDr iver RSED rsrc 
PDriver.c 99222 TEXT 
PDriver.c.o MPS OBJ 


Messing Around in Assembler: 
The Glue 

The specially assembled headers for the printing code re- 
sources are concentrated in one source file, and are now much 
easier to deal with. The MPW code is assembled in modules, 
using the PROC...ENDP directive pairs. All modules are kept 
in one object file. When the glue is linked with each C object file, 
the linker option “-m <module>” is used to determine the start 
address of the code resource. You have to name the glue file first 
on the linker command line, and have the entry point be the first 
module in the glue file which is picked up by the linker, in order 
to have the header appear at the top of the linked code resource. 
The structure of the assembler headers was discussed in the 1987 
article, and is the same here. 

The Aztec glue is a little different, since the Aztec linker 
does not have a“-m” switch, and is not smart enough to pluck out 
the correct startup routine. Conditional assembly takes care of 
this. If you compile with Aztec, you just get four “.o” glue files 
instead of one. In order to prevent a conflict of entry points, the 
Aztec Makefile creates a special version of the runtime library 
with the default entry point removed. 

The assembler glue defines some read-only constant data 
using “dc.b” and “dc.w” directives. This is because the MPW C 
compiler will not define string and array constants with PC- 
relative addresses. Since you have to have the glue anyway, why 
not make use of it? This is a convenient place to store device- 
dependent things like escape codes. Some C compilers do allow 
definition of string constants within source files which are to be 
linked into stand-alone code resources, but the trend appears to 
be to move away from this. Use of such also reduces portability. 

The Aztec C libraries appear to be missing a glue routine for 
. 15МРРОреп(). І have supplied assembler glue for this. 


The Style Dialog: 


Image Scaling Strategies 
This printer file includes a number of named ‘PREC’ re- 


DMP-110 v1.0 


Default Scale КУ 


Stule: 


Compatible . B 
Last Used Print Record 
Shrink To Fit My 
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Sources. A list in the Style Dialog allows the user to choose 
between them. Only one paper size is currently allowed, but a 
number of scaling factors are supplied. Each style is appropriate 
for a particular kind of application program or printing effect. 
This is a convenient dialog to use during development, since the 
dialog code doesn't have to know a lot about the printer's 
capabilities, and you don't have to recompile to try outa different 
‘PREC’. The printing code figures out at run-time how big the 
paper is, and how to scale the image in the Printing Port before 
sending it to the printer. If you design a printer driver which 
allows a number of different options which are independent of 
each other, then a more elaborate dialog box might be appropri- 
ate. 

When one of the list cells is selected and the dialog is 
confirmed, the dialog code copies the appropriate fields from the 
‘PREC’ resource whose name matches the selected cell. The 
dialog code also records the resource number of the chosen 
‘PREC’ in one of the private fields of the Print Record which it 
returns to the application, and uses this information to choose the 
style to select when putting up a new Style Dialog. This means 
that the last-chosen style for a document is “remembered” if the 
application saves the Print Record. 

Most of the Print Records supplied with this printer file 
specify Picture-scaling to enlarge the printed image before send- 
ing it to the printer. In order to understand the effect of scaling 
on the appearance of the printed output, it is necessary to 
understand the differences which exist between the capabilities 
of applications to cope with scaling. 

Paint programs print images strictly as BitMaps. Whatever 
you have on the screen is mirrored, bit for bit, in the printing 
GrafPort when using one of these programs. These usually 
cannot scale images themselves, nor do they produce images 
which can be scaled attractively. HyperCard is a perfect ex- 
ample. 

Font-oriented programs, such as word processors, provide 
the ability to adjust the spacing between characters when printing 
justified text. This may cause problems when we try to print an 
image at a different resolution from that in which it has been 
drawn originally. 

For scaling to be successful, a larger size font must exist, or 
the text will be printed in a scaled font, which will not be 
attractive. If we scale an image containing justified text by anon- 
integral factor, then quantization errors in text positioning cause 
Justification to fail. This is a problem with the DMP-110, since 
there is no way to divide 72 dpi (screen) evenly into 120 dpi 
(paper). A way around this is to provide a Printing Portresolution 
of 60 dpi, and scale by 2, but this means the apparent size differs 
from screen to paper, and results are not really WYSIWYG. 

Another problem arises when we scale by an integral 
amount, and the sizes of characters in the font family are not 
linear. For example, the capital ‘A’ in Times 12 has a width of 
8, but the capital ‘A’ in Times 24 has a width of 17. If the 
character sizes are not linear, then justification fails when the 
Picture is enlarged, even if by an integral amount. Screen fonts 
like Geneva always print with justification preserved if the 
Output Picture is scaled by an integral amount, because character 
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sizes are linear. LaserWriter fonts, on the other hand, seldom 


print correctly under these conditions, because character sizes 


are not linear. The printer file needs to exchange some informa- 
tion with the Font Managerin these cases,so that non-linearfonts 
will be positioned correctly. Since I don’t do this, my printer file 
will not print LaserWriter fonts so that the right ends of justified 
lines are properly lined up. 

The most “advanced” printing application type is a program 
which handles images as a collection of objects. The size of an 
object is determined using non-screen units such as inches or 
centimeters, and the program can handle practically any printer 
resolution you throw at it. Since these programs do not store 
images as collections of bits, but rather as drawing instructions, 
they are (should be) able to draw an object to the correct scale no 
matter what the printer resolution or paper size. The only real 
limitation here is that, again, scaling of text is limited by the 
collection of installed fonts. Examples are MacDraw and similar 
object-oriented drawing programs, CAD programs, and Ver- 
saTerm PRO when printing TekPrint files. 

The Print Records provided by this dialog provide dot- 
addressable graphics for BitMap and drawing programs, a 
"Compatible" or near WYSIWYG mode, and a scaling factor 
which preserves text justification while allowing use of screen 
fonts, but not all three at once. With another printer and a more 
ImageWriter-like resolution, you may do better. Remember that 
the numeric values stored in my ‘PREC’s will not produce 
attractive results with your printer, unless it has the same resolu- 
tion as mine. The comments in the resource definition file show 
what I try to achieve with each Print Record. 

A certain amount of experimentation is necessary to deter- 
mine what the Style Dialog should put in the Print Records, in 
order to achieve any special effects which your printer is capable 
of. I recommend using a simple interface such as that above 
while you are experimenting with printing styles, and then move 
to a more elaborate, customized dialog when you have deter- 
mined what kind of results you get from your printer and your 
Macintosh. 

The Device Interface: 
Talking to the Chooser 


Chooser === === 


, Select Speed and Click on a Port. 


1 | 


| User Name: 


Cd ш : : 
ImageWriter LaserWriter 


i @ Active 
Laser Write... SerialPrinter СУ : 


ABPIRTRIK Q Inactive 


The file type for this printer file is “РКЕК”, so that we can use 
a Chooser Device Package interface to solicit configuration 
information from the user. The Chooser's list is used to put up 
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alist of baud rates, and the two Chooser buttons are used to select 
which serial port to use. Because this printer file is written to be 
device-dependent, there are no further options which may be set 
from the device package. Device-dependent parameters like 
escape codes are not changed by the user. 

When the user clicks one of the buttons or list items, the 
device package would like to communicate the new settings to 
any currently open printer driver which belongs to us. This is 
implemented here simply by changing the ‘HEXA’ resource and 
writing it out to the resource file. Since this printer file imple- 
ments high-level printing jobs and screen dumps only, each 
printing request is treated as a separate print job, and the new 
settings will be picked up before any more printing is done. If you 
decide to implement low-level calls, then you have to figure out 
a way to communicate settings changes from the device package 
to the driver. This is not easy. 

The device package checks for a system version of 4.1 or 
newer, and puts up an error Alert if the device is selected, the 
driver was compiled to use “PrintTraps.h,” and the system is too 
old. If AppleTalk is active and the printer port button is clicked, 
then the device package informs the user that this is an impossible 
choice. (There is no way to dim the left button, except by 
emptying the Chooser's list.) 


The Driver: 

This driver is similar in structure to the driver described in 
my previous article, but it does have some significant enhance- 
ments. The driver does not use any development-system-spe- 
cific tricks to maintain private storage. Each active routine in the 
driver performs a single function, then cleans up after itself when 
done. Support for low-level printing functions is removed. 

The driver only does screen dumps. The screen dump 
routines use essentially the same algorithms that are used by the 
high-level *PDEF' code, so I won't discuss them in any detail. 
They will, however, have to be changed if your printer accepts 
different graphics codes from the ones mine uses. The hardest 
task is to find the Rect which encloses the top window, since the 
portRect doesn't include the structRgn of a window. If anyone 
has a better method of finding this Rect, I would be interested in 
hearing from you. 

The Open, Close, and Status routines simply return noErr. 
The Control routine opens the chosen serial port, dumps the 
screen or top window if called for, closes the serial port, and 
logically should return an error code if an error occurred during 
printing. If the control routine does return an error code, 
however, the ‘FKEY’ which calls it for a screen dump just tosses 
the error code in the byte bucket, assumes that the driver was not 
open, opens it, and calls the control routine again. For this reason, 
this driver control routine always returns noErr. The driver has 
no global storage, doesn't do anything with it's device control 
entry, and is in general quite friendly to other parts of the System. 


Coping with Errors: 
Making the Best of a Bad Time 
This driver does much more complete error checking than 
the driver in my previous article did. 
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This printer cannot use the printer port 
now because AppleTalk is active. Please 


either turn off AppleTalk, use the modem 
port instead, or choose another printer. 


My driver is a “РКЕК” device, so it gets to use the Chooser 
Device Package interface for such things as baud rate selection. 
This also means it does not get the “automatic” serial port 
selection which the Chooser does for ‘PRES’ devices like the 
ImageWriter. А соттоп user error is to turn on AppleTalk when 
the driver has been configured to use the printer port. When 
printer driver is opened it finds AppleTalk on, but its configura- 
tion resource tells it to use the printer port. The Alert box above 
tells the user that this has happened, and the driver closes itself. 
Other open errors are possible, but much less common. These are 
handled by simply closing the driver, and returning an error code. 

Aside from errors which may occur during the driver's open 
routine, there are three types of error which I look for in the 
‘PDEF’, First, the user may type command-’.’ at any time during 
printing. The routine pointed to by the prJob.pIdleProc in the 
print record is called often during high-level printing, and sets 
PrSetError() to other than noErr when this happens. (The default 
routine which I supply now uses ilOAbortErr instead of iPrAbort 
for this purpose.) The printing code allocates temporary output 
buffers to use when translating BitMaps, and sets PrSetError() to 
memFullErr if NewPtr() ever returns nil. Finally, errors may 
occur during a write attempt to the serial port. Serial port errors 
are rare, but should be anticipated. 

Another possible error is that free memory might run out 
when the application is drawing into the Printing Port, and the 
system is filling a PicHandle with drawing commands. The only 
thing I do about this is hope that it doesn't happen! 

The procedure for handling aborts in printing ‘PDEF’s and 
in the driver is discussed below. 

The top-level routine calls setjmp() before sending any 
characters to the printer, and stores the jmp Би] array and IO 
Parameter block in a data structure which is passed down the 
calling sequence. All serial port output is done through the 
routine asyncwrite(), which takes a pointer to the data structure 
and a pointer to an idle routine as parameters. Asyncwrite() 
Issues an asynchronouswrite request to the serial driver, and 
repeatedly calls the idle routine until the request has been 
completed. (The ioResult field of the parameter block used to 
issue the write request will remain positive until the write request 
has been completed.) If a user abort (command-’.’) occurs, then 
the idle routine calls PrSetError() with ilOAbortErr. (The default 
idle routine I include does this, but an application-supplied 
routine may arrange for printing to be halted in another way.) 
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After the idle routine returns, asyncwrite() checks PrError() to 
see if an abort or error has been logged. 

If asyncwrite() detects that an abort or error has occurred 
during the write, it first calls РВКІШОО to kill any pending serial 
port output, then calls longjmp() to get back to the top level 
printing routine. The top level of the control routine does any 
necessary cleanup, and then calls PrSetERror(iIOAbortErr). 

When the write requestis complete, asyncwrite() checks the 
ioResult field of the IO Parameter block for the presence of an 
error code, and longjmp(s back to the main level if it finds one. 

Sincea printer is a slow device, itis important to detect errors 
quickly, particularly user abort errors. A user abort may meana 
mechanical problem with the printer, so we want to detect it and 
kill any pending output at the earliest possible moment. This 
method provides that ability, but it does have one problem with 
the DMP-110 printer. High resolution graphics are sent to the 
printer by first sending an escape sequence telling the printer to 
expect a number of two-byte codes between 1 and 959, then 
sending the codes. If the printing code is sending a sequence of 
graphics codes, all of which are non-zero, then the codes will be 
sent all at once. This can happen if the image contains a 
horizontal line, for instance. If an abort is sensed in the middle 
of a long sequence of graphics codes, then the printer will be left 
hanging, expecting perhaps several hundred more graphics 
codes. Since all characters are valid graphics codes in high 
resolution mode, there is no way to get the printer out of this state, 
short of shutting it off and turning it on again. This may cause the 
user some unpleasantness by leaving the printer in an undefined 
State, but perhaps less than if the driver tries to print to the end of 
the line, while the ribbon or paper is jammed. If your target 
printer has a means of resetting itself with a serial port command 
at this time, you would want to send the reset command before the 
control routine returns. 

A possible source of problems under MultiFinder is that the 
printer driver is a shared resource, and so it is highly unlikely that 
the printer driver’s close routine will ever get called when an 
application exits. This means that the serial port might get left 
open, and the user can’t use it for something else. For this reason, 
the driver doesn’t maintain any storage, and closes the serial port 
before it returns. Each screen dump or high-level printing job is 
handled separately, and everything is cleaned up afterwards. 
This means that if the user changes printers, or wants to use a 
terminal program on the same serial port after she is done 
printing, then she won’t have any problems doing so. 

Finally, there is one more source of errors, if the programmer 
decides to use “PrintTraps.h” instead of “Printing.h.” This is best 
explained by the the Alert box: 


© E 


This Printer requires System 4.1 or newer! 
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My copy of the printer file uses “PrintTraps.h” because (a) 
it is strictly for my personal use, and (b) I use the newest system 
file I can get at all times. If you want to write a printer file for 
commercial use, then “Printing.h” is highly recommended. 
Using “Printing.h” adds about 2k to the size of the complete 
printer file. If you plan to write a printer file for a color device 
which uses Color QuickDraw, or need any features in System 4.1 
for any other reason, then you might as well go ahead and use 
“PrintTraps.h.” 


Background Printing: 
Working with MultiFinder 
The default idle procedure used when high-level printing is 
active calls WaitNextEvent() if the trap is implemented, and 
SystemTask() and GetNextEvent( otherwise. This allows a user 
to puta printing application into the background under MultiFin- 
der, and allows desk accessories to continue running under 


sss OMP-110.rsre 


“ 


ШІ о cencel printing hold down 
i "the 3€ key end type а period(.). 


A2Glue.asm AZHeaders.c detaball 


T T = 
| 2 items | AzMakefile 


A2Final.r 


UniFinder. Combined with the asynchronous method of writing 
to the serial port, this gives the user use of the machine when the 
serial driver is waiting to send characters. In the screen dump 
above, the Finder is printing the directory of the “src” folder to 
the DMP-110 printer, and ResEdit is running in the foreground. 
Performance of ResEdit is just fine under these conditions. This 
is not the scheme that Apple has chosen to use for background 
printing, but pending documentation of Apple’s scheme it is an 
acceptable alternative. 

One problem with this scheme is that most applications will 
put up a dialog box when printing similar to the Finder’s, above. 
MultiFinder doesn’t like to swap out an application when the 
front window is a dBoxProc type of window. Changing the 
procID of the Finder’s printing dialog box to documentProc 
allows the user to freely swap the Finder in an out of the 
foreground while printing, and the Finder doesn’t know a thing 
about it! Setting the “Can Background” bit in the application’s 
‘SIZE’ resource is also necessary to an older application to be 
given background time if you swap it out while printing. 

Printing speed seems to be about the same under these 
conditions as it is with the printing application in the foreground 
or operating without MultiFinder. With asynchronous writes, 
and the limiting factor being the speed of the print head, there is 
usually a lot of free time available when printing. 
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The driver’s procedure for dumping the screen does not call 
WaitNextEvent(, for the simple reason that allowing the user to 
move windows around would really muck up the output! 


BitMap to Dot-Matrix: 
Nuts and Bolts 

This section shows how I transform a QuickDraw BitMap to 
a series of graphics codes which my printer can understand. It is 
necessarily device-dependent. Your output format may vary, 
depending on the characteristics of your printer, but your input 
will be the same if you are talking to a black-and-white printer. 
Writing a printer file for a color printer is “left as an exercise for 
the reader." 

The DMP-110 accepts high-resolution printing codes in the 
following format. A two-byte escape code is used to signal high- 
resolution graphics. This is followed by another two-byte code 
which tells it how many columns to print. Each 16-dot column 
is specified by a two-byte code. In order to print n columns of 
graphical data we send the two-byte graphics code, two-bytes to 
specify n columns, and then n*2 bytes of graphical data. There 
are 959 possible 16-dotcolumns on one line, for a printable width 
of just under eight inches. 

The first byte specifies the top eight dots, and the second 
specifies the bottom eight dots. The low-order bit in the first byte 
is on if the top dot in the first column is to be printed, off 
otherwise. The high-order bit in the first byte is responsible for 
the eighth dot in the first column. The second byte in the two-byte 
sequence accounts for the ninth through sixteenth dots in the first 
column. This is continued until 2*n bytes are sent, with the last 
byte specifying the bottom eight dots in the last dot-column. 
There is also a four-byte sequence for positioning the print head 
at any of the possible 959 printing positions. 

Because of the way the 68000 series processors store nu- 
meric quantities in RAM, the first or top dot corresponds to the 
eighth bit in the first byte sent, which is the least significant bit. 
This is very important to remember because the Toolbox Utilities 
routines which are used to move bits around access them in the 
opposite order. In order to copy a bit from a BitMap into a dot- 
position in the first or any other column, we have to take into 
account the logical bit-reversal which occurs during this process. 
A sixteen pixel deep Rect in the source BitMap is copied to an 
output buffer for the DMP-110 in the following fashion. 

A double loop loops over the dot-columns to be printed, up 
to 959 in number. Two inner loops fill the top and bottom bytes 
with bits from the source BitMap. A QuickDraw BitMap consists 
of bytes which are laid on their sides, so that the first pixel in the 
first row is specified by the first bit in the data pointed to by the 
baseAddr field of the BitMap. This bit is mapped to the least 
significant bit in the first byte in the output buffer. In the scheme 
used by the Toolbox Utility routines, the first bit in the source 
BitMap is mapped to the eighth bit in the output buffer. The 
seventh bit in the first output byte comes from the first bit in the 
second row of the source BitMap. The first inner loop fills the 
firstoutputbyte with the first bits from each of the firsteightrows 
in the source BitMap, and the second inner loop uses the first bits 
from the ninth through sixteenth rows of the BitMap to fill the 
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second output byte. The outer loop continues until all of the dot- 
columns in one 16-dot high printing row have been filled. 

Landscape style printing should be easier to implement. If 
the BitMap is scanned in the correct direction then bits within 
bytes will not have to be moved around, but only whole bytes. 

A number of schemes may be used for sending the output 
buffer to the printer at this point. The entire row of graphics codes 
might be sent at one time, simplifying the computation. If, 
however, the output page will contain many white areas, it is 
advantageous to reposition the print head during printing so as to 
skip over white areas. The DMP-110 requires four bytes to 
position the head, and two bytes to print a single blank column. 
Accounting cost in terms of number of bytes sent through the 
serial port, if we skip over three blank columns we win, if we skip 
over two columns we break even, and if we skip over one column, 
welose. How to optimize the printing process is harder to figure 
out fora whole row, but itis probably correct to assume that white 
columns will be grouped together, and that some improvement is 
to be expected by skipping over any blank dot-column. The 
printing head is then positioned before the next non-blank print- 
ing area. Moreimprovement might be expected by skipping over 
only blank dot-columns where they are grouped, but at the 
expense of having to write more code. 

A BitMap is printedin this scheme by first breaking itup into 
areas which are sixteen pixels deep. Each such area is converted 
and sent to the printer, followed by a carriage return and a high- 
resolution graphics linefeed. By looping over the whole BitMap, 
an exact image of the BitMap is made on paper. 

This general scheme will work for any dot-matrix printer 
which accepts byte codes to specify a dot-column, if it is first 
modified to use the device-dependent protocol needed by the 
printer. Changes to this source code to work with another printer 
should involve changing escape codes and reworking the BitMap 
translation routines only. 

First, look in the printer manual to determine how many 
vertical dots are printed in each dot-column. This determines 
how many rows of the source BitMap may be printed at once. 
Second, find out how the dots in a column are encoded into bytes 
to be sent to the printer. This will most probably be top-dot-first 
using Intel or VAX ordering. Third, map the bits in the BitMap 
to a suitable output buffer. Fourth, and this is optional but 
recommended, determine whether optimization of output byte 
codes to take advantage of repositioning the print head is pos- 
sible. Fifth, send the printing codes to the printer along with the 
proper device-dependent escape codes and a graphics line feed. 
Finally, if the printer is capable of using form feed codes to 
separate pages, send the form feed at the end of the page. 
Otherwise, advance the paper using more line feeds. 


BitMap to Band: 
Capturing the Image 
This section details how to trick an application program into 
drawing a picture in our printing GrafPort, how to “play back" the 
picture in bands using DrawPicture(), and how to send the bands 
. onto the BitMap translation routines. In order to write a printer 
file for another device, the size of the BitMap, the size of the 
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GrafPort’s portRect, and the number of bands will have to be 
tailored to your printer. The general principles remain the same, 
and I believe that the method I use here is a good general purpose 
method for capturing QuickDraw images to be sent in high- 
resolution mode to any dot-addressable device. 

My code does not take advantage of a printer’s native fonts, 
since all information is printed in graphics mode. It relies on 
QuickDraw and on Macintosh screen fonts for all text printing. 
How tocombine graphics and use of a printer's native fonts is left 
as “an exercise for the reader” or perhaps a future article. 

The first routine to be called in a printing job is PrOpen- 
Doc(). This routine sets up the fields of a Printing GrafPort 
(TPrPort) to match those in the Print Record passed to it, allocates 
necessary storage, and initializes variables used in the printing 
job. The IGParam[1-4] fields of the TPrPort are used to hold all 
printing variables particular to this printing job, and dynamic 
storage is allocated in a tree structure branching from pointers 
stored in these fields, which are given preprocessor names for 
readability. This routine allocates a total of about 3k of storage. 
If the storage cannot be found, then it calls 
PrSetError(memFullErr), and leaves things in a state where 
PrCloseDoc can clean up properly. The application will call 
PrCloseDoc if there is an error logged after this routine returns. 

Use of distinct blocks of storage to hold the printing vari- 
ables complicates the process of allocating and disposing of 
them, but allows for the use of an output BitMap whose size is 
determined at run time. 

The dimensions of the TPrPort are taken from the 
prinfo.rPage field of the Print Record, and the dimensions of the 
port's BitMap are taken from the prXInfo field. The bounds Rect 
ofthe BitMap is sized so asto beable to break up the portRect into 
several "bands" used in printing. These must agree with the 
physical capabilities of the printer. The serial port is opened for 
this printing job, and a pointer to the TPrPort is returned to the 
caller. 

The PrOpenPage() routine is called before every page to be 
printed. It sets the port to the Printing Port, and opens a new 
picture. All subsequent drawing in this port is saved in the 
picture, whose handle is saved in one of the IGParam fields of the 
Printing Port. 

The PrClosePage() routine does all the work of translating 
and sending the saved picture to the printer. It first calls 
ClosePicture to finish the picture definition. Then the portRect 
of the Printing Port is resized according to the information in the 
prInfoPT field of the Print Record, so as to reflect the final page 
size. This information is taken from the Print Record, and not 
from the code, to allow for easier adaptation to other printers. 
Note that you don't have to print the picture at this point, you can 
do anything you want to with it. You could for instance save the 
images printed by an application in a picture file or a paint file. 

Printing is accomplished as follows, for each band in the 
printing page: 

The Printing Port's BitMap is first aligned with the band to 
be printed, using the MovePortTo() Toolbox call. The Printing 
Port's portRect is erased. DrawPicture() is called to draw the 
application's picture in the expanded portRect, thus correctly 
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filling the bits in the BitMap for the band to be printed. The 


routine dumpbits() is then called to convert and send the band to- 


the printer. 

This process is repeated until the entire picture has been 
printed, and then KillPicture() disposes of the picture Handle. 

Since this is the routine which communicates with the serial 
port, and it also calls DrawPicture() several times, this is the 
routine wherein the printing code spends the most time. The 
prJob.pIdleProc routine should be called repeatedly whenever 
the printing code is waiting for the serial driver to finish a write 
request. This is done in the routine asyncwrite(), which also 
checks serial port errors. If this routine ever senses an abort 
attempt or a serial port error, then it Іопрјтр()ѕ back to the top of 
PrClosePage, which calls PrSetError() and returns. 

When the last page has been printed, then the application 
calls PrCloseDoc, which closes the serial port and the Printing 
Port, reclaims all dynamic storage that was successfully allo- 
cated, and exits. 


Putting It All Together: 
Compiling and Stuff 

Compiling the sources is perfectly straightforward, if you 
have the MPW Shell and either MPW C and MPW Asm, or Aztec 
cc and Aztec as. Copy the files from the source disk into a new 
folder, copy either *MPWMakefile" or “AZMakefile” to 
*Makefile," and type “BuildProgram install.” This builds the 
driver, and installs a copy of itin the active System Folder. If you 
are using Aztec C, the script generated by BuildProgram will ask 
you to find an original copy of "sys2:lib:azc.lib." This is copied 
to “{clib}tools.lib” and modified for use with this project, by 
deleting the module containing crt0.o. This step is necessary so 
that the linker will use my assembler glue as the entry point, and 
not crtO. Also make sure that when using Aztec cc, your 
(INCLUDE) environment variable points to the directory con- 
taining the MPW-compatible header files, and not the older 
Aztec header files. 

If you do not have the MPW Shell, and want to build the 
printer file using Aztec Make, then you will have to modify 
AZMakefile to use Aztec Make syntax. Since I purchased the 
“cheap” Aztec C package, I did not get Aztec Make with it. If you 
also bought the “cheap” Aztec package, but do not have MPW 
Shell, then you will have to write a script to compile and link the 
files, or (ugh!) type in the commands by hand. 

Also, MPW users might want to go through their 
“Printing.h” and “PrintTraps.h” files and replace every single 
instance of the keyword "int" with "short." This has nothing to 
do with this project, but it will allow you to call PrGeneral from 
other programs. Presumably, this problem has been fixed in 
MPW C v 3.0. 


Results: 
What Does it Look Like? 

It is difficult to include samples of printed output, since 
MacTutor probably uses a page setup program, and would have 
to scan output I sent them and then paste it back into the final 
article before printing. We can only hope. 
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The most serious flaw with the choice of printer is that the 
resolution is not ImageWriter-compatible. This is a hardware 
limitation of the device I am using, and may not affect your 
efforts. 

The main shortcoming of this printer file is that it does not 
participate in line layout at all, and thus cannot reproduce 
justified text with LaserWriter fonts if the output image is scaled. 
Ihaven'tbegun to investigate whatis required to do this properly, 
and soIdon'tknow how much work is involved in implementing 
this feature. Images containing linear screen fonts like Geneva, 
New York, and Symbol always seem to come out right if the scale 
factor is an integer. 

Bit-mapped images do not produce the same size printed 
output as would the ImageWriter or the LaserWriter in 
ImageWriter-compatible (default) mode. Paint images which 
are scaled by an integral factor come out bigger or smaller than 
they look on the screen as a result, but all the bits are there, and 
in place. You will not have this problem if your printer is capable 
of 72 dpi, or a multiple thereof. 

Word processor programs produce acceptable output if a 
screen font exists in the correct size for QuickDraw to use when 
DrawPicture() iscalled. For example, if a 9-point font is used, the 
image is doubled in size before printing, and an 18-point font can 
be found whose character sizes are twice those of the 9-point font, 
then text is positioned properly on the output, and justification 
works properly. More work is necessary to make the printer file 
work properly in all cases with LaserWriter fonts and others with 
non-linear character sizes. 

Drawing programs like MacDraw work the best with this 
printer file, since these do the work of scaling by themselves. 
With a drawing program, one uses a Print Record which calls for 
no scaling on the part of the printing code, and the drawing 
program can then place and size objects to best advantage. These 
programs look in the prStl field of the Print Record to determine 
the paper size, and thus the correct size of the printed object. Such 
programs are capable of producing identically-sized output with 
my printer and my driver as they do with Apple printers and 
Apple drivers. 

Although this printer file has some shortcomings, it does 
allow printing of Macintosh graphics on my DMP-110, which 
had been gathering dust since I stopped using my Radio Shack 
Color Computer. Results are in most cases attractive, and it 
suffices for most of the draft graphics printouts I need. The 
missing features are left for the subject of a future article, or 
perhaps an exercise for the reader. 


Listing: MPW MekeFile 

" file is part of DMP-110 printer driver for the Macintosh 
# series of computers. 

8 Earle R. Horton Wednesday, November 39, 1988 

#8 Makefile for ОМР-110 v1.0. 

8 This is the Makefile for use with MPW C, v 2.0.2. 

CFLAGS = -g 


с.о f .c 
C {CFLAGS} (default}.c -o (default).c.o 

ао] .a 

Asm (default).a -o (default).a.o 

DMP- 110 f PACK PDEF0 PDEF4 PDriver DMP-110.rsrc mpwfinal.r 
Rez -о ОМР-110 -c ‘Dmp1’ -t ‘PRER’ mpwfinal.r 
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SetFile DMP-110 -a B 
DMP-110.rsrc ff DMP-110.rsrc.r makefile 
rez -o DMP-118.rsrc -t ‘rsrc’ -c RSED DMP-110.rsrc.r 
PACK ff MPWGlue.a.o pack.c.o 
link MPNGlue.a.o pack.c.o à 
-m PACKENTRY -d à 
(libraries) interface.o -rt PACK--4096 -sn 
Mainz^Chooser Device” д 
-ss 100000 -o PACK -t ‘rsrc’ -c RSED 
PDriver ff MPWGlue.a.o PDriver.c.o 
link -m DriverEntry -d MPWGlue.a.o PDriver.c.o 
(clibraries)cinterface.o д 
(libraries) interface.o (clibraries}CRunTime.o 
{clibraries}StdCLib.o à 
-rt DRVR=-8192 -sn Main=.XPrint д 
-ss 100000 -o PDriver -t ‘rsrc’ -c RSED 
PDEFÜ ff MPWGlue.a.o PDEFO.c.o 
link -m PRINTENTRY -d MPWGlue.a.o PDEF0.c.o 
(clibraries)cinterface.o à 
(libreries)interface.o (clibraries)CRunTime.o д 
(clibraries)StdCLib.o -sn Main=*Draft Printing Code” à 
-rt PDEF=0 -ss 100000 -o PDEF® -t ‘rsrc’ -c RSED 
PDEF4 ff MPWGlue.a.o PDEF4.c.o 
link -m DIALOGSENTRY -d MPWGlue.a.o PDEF4.c.o 
(clibraries)cinterface.o à 
(libraries) interface.o -sn Main-PrDialogs 9 
-rt PDEF=4 -ss 100000 -o PDEF4 -t ‘rsrc’ -c RSED 
install f — DMP-110 
duplicate -y DMP-110 *(systemfolder)DMP- 110^ 
clean 
delete -i "(systemfolder)testDMP- 110^ 9 


‘files -m 300 -t rsrc ;files -m 300 -t PRER; files -m 300 - 


t '0BJ '' 
PDEFÜ.c.o f DMP-110.h 
РОЕҒ4.с.о f DMP-110.h 
PDriver.c.o f DMP-110.h 
pack.c.o f DMP-110.h 


Listing: compat.h 

/* FILE is intended for use with MPW C 2.0 Interface files 
which generate InLine code for routines that call the 
ToolBox with points by value & strings as Pascal strings. 
It should be included AFTER any Macintosh #include files. 
See Appendix H of the MPW C 2.0 manual for details. 

file allows use of MPW C 2.0 standardized ToolBox calls 
using spelling from Inside Macinstosh, and not all upper 
case, as is used in MPW C 2.0 header files. Please note 
that use of this means that you no longer have access 

to the C-language versions of the ToolBox calls. 

It is rumored that this file will no longer be necessary 
with MPW C 3.0. (?) 

If you like to pass C strings to ToolBox, do NOT include 
this FILE. */ 

"ifdef MPU68000 /* Aztec C, v 3.6c. */ 

/* -D_INLINE on cc’s command line is all that’s required. */ 
"else 

8def ine NewControl NEWCONTROL 

define SetCTitle SETCTITLE 

define GetCTitle — GETCTITLE 

8def ine DragControl DRAGCONTROL 

8def ine ТесіСопіго1 TESTCONTROL 

def ine TrackControl TRACKCONTROL 

def ine FindControl FINDCONTROL 

8def ine OpenDeskAcc OPENDESKACC 

8def іле FindDItem FINDDITEM 

Sdefine NewDialog NEWDIALOG 

Sdefine ParamText РАРАМТЕХТ 

Sdefine GetIText — GETITEXT 

Sdefine SetIText — SETITEXT 

8def ine NewCDialog NEWCDIALOG 

def ine GetVol GETVOL 

8def ine SetVol SETVOL 

Sdef ine UnmountVol UNMOUNTVOL 

ttdef ine Eject EJECT 
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def ine FlushVol FLUSHVOL 

Sdefine Create CREATE 

8def ine FSDelete FSDELETE 

8def ine FSOpen FSOPEN 

Sdefine OpenRF OPENRF 

8def ine Rename RENAME 

8def ine GetFInfo GETFINFO 

8def ine SetFInfo SETFINFO 
Sdefine SetFLock SETFLOCK 
Sdefine RstFLock RSTFLOCK 
Sdefine GetFontName GETFONTNAME 
def ine GetFNum GETFNUM 

"define LCellSize LCELLSIZE 

8def ine LClick LCLICK 

def ine LNew LNEW 

8def ine NewMenu NEWMENU 

Заде? ine AppendMenu APPENDMENU 

Sdef ine SetItem SETITEM 

8def ine GetItem GETITEM 

def ine InsMenuItem INSMENUITEM 
def ine MenuSelect MENUSELECT 

def ine EqualString EQUALSTRING 
8def ine RelString RELSTRING 

8Sdef ine UprString —X UPRSTRING 

8def ine DIZero DIZERO 

def ine NumToStr ing NUMTOSTRING 
define StringToNum STRINGTONUM 
Sdefine SFPutFile —XSFPUTFILE 

def ine SFPPutFile SFPPUTFILE 
"define SFGetFile —SFGETFILE 
"define SFPGetFile SFPGETFILE 
Sdefine IUDateString IUDATESTRING 
Sdefine [UDatePString IUDATEPSTRING 
Sdefine IUTimeString IUTIMESTRING 
8define IUTimePString IUTIMEPSTRING 
8def ine IUConpString IUCOMPSTRING 
8define IUEqualString — IUEQUALSTRING 
def ine DIBadMount DIBADMOUNT 

8Sdef ine DrawString DRAWSTRING 

8def ine StringWidth STRINGWIDTH 
8Sdef ine StuffHex STUFFHEX 

8Sdef ine AddPt ADOPT 

8def ine SubPt SUBPT 

Sdefine EqualPt EQUALPT 

8def ine PtInRect PTINRECT 
Sdefine Pt2Rect PT2RECT 

Sdefine PtToAngle PTTOANGLE 

8def ine PtInRgn PTINRGN 

def ine StdText STDTEXT 

Sdefine CreateResFile CREATERESF ILE 
Sdefine OpenResFile OPENRESFILE 
Sdefine OpenRFPerm OPENRFPERM 


tdef ine GetNamedResource GETNAMEDRESOURCE 
8де? ine Get iNamedResource СЕТ INAMEDRESOURCE 


define GetResInfo GETRESINFO 

8def ine SetResInfo SETRESINFO 

def ine AddResource ADDRESOURCE 
8def ine GetAppParms GETAPPPARMS 
8Sdef ine OpenDriver OPENDRIVER 

fidef ine TEGetOffset TEGETOFFSET 
"define TEGetPoint TEGETPOINT 

8def ine TEClick TECLICK 

Sdefine NewString NEWSTRING 
Sdefine SetString SETSTRING 
Sdefine GetIndString GETINDSTRING 
Sdefine DeltaPoint DELTAPOINT 

def ine ShieldCursor SHIELDCURSOR 
Sdef ine NewWindow NEWWINDOW 
"define SetWTitle SETWTITLE 

8def ine GetWTitle GETWTITLE 

"def ine NewCWindow NEWCWINDOW 

def ine GrowNindow GROWWINDOW 

8def ine DragWindow DRAGWINDOW 
define TrackGoAway TRACKGOAWAY 
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Sdefine FindWindow FINDWINDOW 
8def ine PinRect PINRECT 
def ine DragGrayRgn DRAGGRAYRGN 
8def ine TrackBox TRACKBOX 
endif 


Listing: DMP-118.h 

/* Earle R. Horton. 

* Wednesday, November 30, 1988 
* All rights reserved.*/ 

tifndef _ DMP. 

8def ine —DMP_ 

/* Def ine BACKWARD_COMPATIBLE to use printing glue, 
ж rather than PrGlue trap. Penalty is about 2k size іп 
* final printer resource file.*/ 

ifdef BACKWARD COMPAT IBLE 

include <Printing.h> 

else 

Sinclude «Printtraps.h? 

endif 

include (setjmp.h»? 

Sinclude <Devices.h> 

Sinclude «AppleTalk.h» 

include «Files.h? 

include <бегізі.һ» 

Sdef ine PrintErr (%(5һогі *2(0x0944)) /* Not used if PrGlue 

trep found. */ 

Sdef ine SHEETDIALOG (-8190) 

ttdef ine DONEITEM 1 

ftdef ine STOPITEM 2 

де? ine КЕ$ 110 (-4080) 

ttdef ine RES2ID (-8192) 

Sdefine SYSNEEDED (0х0410) 

Sdefine ATALKALERT  (-4078) 

Sdef ine SYSVERSALERT (-4079) 

Sdef ine iPrRelease 3 

def ine GRAFREZZ 120 

define NORMALREZ 80 

Sdefine COMPATREZ 72 

Sdefine VERSION 3 

Sdefine iFMgrCtl 8 

Sdefine iPrEvtCt] 6 

Sdefine IPrLFEighth 0x0003FFFE 

ifndef FALSE 


Sdef ine FALSE 0 
Sdefine TRUE 1 
Rendif 


Sdefine iPrPgMax 9999 
Sdefine iPrPgFst 1 
typedef struct ( 

struct QElem *qL ink; 


short аТуре; 
short ioTrap; 

Ptr ioCmdAddr ; 
ProcPtr ioCompletion; 
05Егг ioResult; 
char *joNamePtr ; 
short ioVRef Num; 
short ioCRef Num; 
short csCode; 
long 1Param 1; 
long 1Рагат2; 
1ong 1Param3; 


) PrParam,*PPrParam; 
tupedef struct( 
short  dummy[5]; 
) pconfig,*Pcfg,**Pfg; 
"def ine pport (C*settings2-? dumny(0 1) 
8def ine pbaud (C*settings)-? dumnyL 11) 
Sdef ine XonXoff (C5settings) dummy (21) 
def ine MAGIC ‘Dmp1’ 
define PORTOPEN ‘OPEN’ 
Sdefine dOpened 5 
typedef struct ( 
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ParamBlockRec iopb; /*writing to serial driver. */ 


jmp_buf abor tbuf ; 

Ptr obuf ; 
}Dstorage, *DPstorage, **DHstorage; 
tendif 


Listing: MPWGlue.a 

;; Glue for Printer Driver code resource headers MPW C. 

;; header for each type of resource is placed in a separate 
2; module using Asm PROC directive. The *"-m^ option to the 
;; linker makes it the entry point to linked code resource. 
;; Earle R. Horton. А11 rights reserved. 

;; Tuesday, December 13, 1988 

;; Some of Glue routines contain data. This is read-only! 


CASE ON 
SEG “Main” 
INCLUDE ‘SysEqu.a’ 


myDrvrFlags EQU CCi««dCtlEnable) + Ci««dStaetEneble) + 
(1<<dNeedGoodBye)) << 8 ; Flag byte. 
;; The header for the 'DRVR^ resource. 
DriverEntry PROC EXPORT ;; ‘DRVR’ starts here. 
IMPORT туРгОреп ; Open routine 
IMPORT myPrPrime ; prime 
IMPORT myPrControl ; control 
IMPORT myPrStatus ; status 
IMPORT myPrClose  ; close 
CODE 


; control and status enable only 


DC.W  my0rvrF lags 
0 ; doesn’t need time 


З 


DC.W 0 ; no events 

DC.W 0 ; no menu 

DC.W muPrOpenCall-DriverEntru ; Offsets to driver 
routines 


DC.W muPrPrimeCall-DriverEntru 
DC.W — myPrControlCall-DriverEntry 
DC.W — myPrStetusCall-DriverEntry 
DC.W — myPrCloseCall-DriverEntry 
STRING PASCAL 


DC.B ' Print’ ; Driver name as Pascal string 


DC.W 0 ; Zero for word-align. 

dummyheader ; Make it look like а procedure for 
LINK A6, #9 ; MacsBug 

myPrOpenCal | 


PEA myPrOpen j; SP -> desired driver routine. 

BRA.S Са110гімег ;; Jump interface to call real 
routine. 
nyPrPr imeCal] 

PEA myPrPrime 

BRA.S  CellDriver 
nyPrControlCall 

PEA myPrControl 

BRA.S Са110гімег 
nyPrStatusCall 

PEA myPrStatus 

BRA.S  CallDriver 
myPrCloseCall 

PEA myPrClose 
Callüriver 

MOVE.L A1,-CSP) 

MOVE.L A0,-C(SP) 

MOVEA.L 8(SP2,A0 

JSR САЙ) 


;; Times 5. 


;; Push ptr to dev control entru. 
;; Push pointer to parameter block. 
;; Get routine address. 
;; Call driver routine. 
;; Result is in DØ. 
;; Restore registers. 
MOVE.L (SP)+,A1 ;; C programs leave stack alone. 
ADDQ.W #$4,АТ ;; Fix up stack pointer. 
BTST "$01,$0006(A0) ;; Immediate call? 
BNE.S  StdReturn ;; Yes, regular return. 
MOVE.L JIODone,-Csp) ;; No, return via IODone 
StdReturn 


MOVE.L (SP)+,A0 
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RTS 


label j; This is for MacsBug. 
UNLK A6 
RTS 
STRING ASIS 
DC.B DMP- 110 ' 
ENDP 
j) The header for the Chooser Device Package. 
CASE OFF 
PackEntry PROC EXPORT 
IMPORT device 
BRA.S devicejump 
deviceID 
DC.W 0 
Packname 
DC.L $5041434B ; 'PACK' 
IDnumber 
DC .W $F000 ; -4096 
Version 
DC .W l 
Flags 
DC.L %0С00Е000 
device jump 
JMP device 
ENDP 


j; The header for the Job and Style Dialogs code. 
CASE OFF 

DialogsEntru PROC EXPORT 
import MyPrintDefault 
import MyPrSt1Dialog 
import MyPrJobDialog 
import MyPrStlInit 
import MyPrJobInit 
import MyPrDlgMain 
import MyPrValidate 
import MyPrJobMerge 
bra.w  MyPrintDefault 


bra.w  MyPrStIDialog 
bra.w — MyPrJobDialog 
bra.w  MyPrStlInit 
bra.w  MyPrJobInit 
bre.w  MyPrDlgMain 
bra.»  MyPrValidate 
bra.w — MyPrJobMerge 
ENDP 


j; Routines to call Pascal procs which are known by address 


;; and not by name. (ProcPtr glue). 
CASE OFF 
CallDigInit PROC EXPORT 
Export CallltemProc 
CallItemProc 
MOVE.L (SP)+,A0 ; Pop return address. 


MOVE.1 (SP)+,A1 ; Pop actual function address. 
MOVE.L A0,-C(SP) ; Push return address. 
JMP (A1) ; Call the Pascal Function 


ENDP 
;; The header for the printing code. 
CASE OFF ; If main code is in Pascal. 


PrintEntry PROC EXPORT 
IMPORT myPrOpenDoc 
IMPORT myPrCloseDoc 
IMPORT myPrOpenPage 
IMPORT myPrClosePage 
bre.w X myPrOpenDoc 
bre.» —myPrCloseDoc 
bra.w — myPrOpenPage 
bra.w muPrClosePage 
ENDP 
CASE ON 

serialdata PROC EXPORT 

; This module consists of read-only data. 


O The Best of MacTutor, Vol. 5 


baud300 EQU 380 
baud600 EQU 189 
baud 1200 EQU 94 
baud 1800 EQU 62 
baud2400 EQU 46 
baud3600 EQU 30 
baud4800 EQU 22 
baud7200 EQU 14 
baud9600 EQU 10 
baudi9200 EQU 4 
baud57600 EQU Ø 


EXPORT AQutName, BOutName, BaudRates, prhireslf 


; Handy storage place for constant strings & data which can 


; be copied by the Driver routines. 
STRING PASCAL 


AO0utName 

DC.B '.K0ut 
BOutName 

DC.B * Bout’ 

STRING ASIS 
prhireslf 

dc.b 3,26,27,%” 

ALIGN 2 
BaudRates 


DC.W baud300 
DC.W baud600 
DC.W baud1200 
DC.W baud1800 
DC.W baud2400 
DC.W baud3600 
DC.W baud4800 
DC.W бау07200 
DC.W baud9600 
DC.W baud19200 
DC.W baud57600 
ENDP 

END 


Listing: Pack.c 


/* Chooser Device Pack code. Described in Device Manager 


* chapter of Inside Macintosh IV. */ 
/* Earle R. Horton. 
* Wednesday, November 30, 1988 
* All rights reserved. */ 
*include «Resources.h? 
include <ToolUtils.h» 
*include «0SUtils.t» 
Sinclude <Dialogs.h» 
Sinclude «Lists.h» 
8def ine PACK 
Sinclude “dmp-110.h” 
Sinclude "compat.h"^ 
Sdef ine - SEG. Main 


/* The Pascal Interface to MPW C 2.0.2 does not fully include 


the List Manager. */ 
®ifdef macintosh 


pascal void LGetCell(Ptr,short *,Cell,ListHandle); 


pascal void LSetCellCPtr,short,Cell,ListHandle); 
pascal void LSetSelect(Boolean,Cell,ListHandle); 
Sendif 


pascal OSErr  device(message,caller,objn&me,zonename,p 1,p2) 


short message,caller; 
StringPtr објпапе, 2опепате; 
А p1,p2; 


Pfg settings; 
ifndef BACKWARD_COMPAT IBLE 
SysEnvRec World; 
(void SysEnvirons(1,&World); 
if(World.systemVersion < SYSNEEDED X 
Cvoid StopA ler t(SYSVERSALERT,nil); 


159 


) 


else 
tendif 
switch(message 2( 
case buttonMsg: 
prsetup(p2); 
break; 
case fillListMsg: 
filllist(p1); 
break; 


case selectMsg: 
settings = (Pfg)(GetResource( “НЕХА” ,RES21D)); 
pbaud = p2; 
break; 


return (noErr); 


/* Fill the list passed to us with the names of baud rates 
ж contained in our ‘STRE’ resource. */ 

filllistClist) 

eo list; 


Pfg settings; 

Cell cell; 

short i; 

char thestring([256]; 

settings = (Pfg)(GetResource( ‘HEXA’,RES21D)); 

(void LAddRow( 11,9, list); 

for( i=; i1<11; 0 
SetPt(&cell,8, i++); 
GetIndString(thestring,RES1ID, i); 

LSetCellC&thestr ingL 1), (short )thestring(8),cell, list); 


) 

SetPt(&cell,0,pbaud); 
LSetSelectC(OxFFFF,cell, list); 
LAutoScroll(list); 


/* prsetup() - Configure serial port.*/ 
prsetup(button) 
as button; 


Pfg settings; 
if (Csettings = (Pfg)CGetResource( “НЕХА” ,КЕ5210222 == nil) 
return; 
if(Cbutton & @xFF) == 1X 
4fCIsMPPOpen())( /* Conflict! */ 
(void)StopAlert(ATALKALERT,nil); 
return;) 
pport = 1; 
)else( 
pport = 0;) 
ChangedResource(settings); 
WriteResource(settings); 


) 


Listing: рдеѓб.с 
/* Draft mode, text-onlu printing code for the Macintosh.*/ 
/* file is part of DMP-110 printer driver for the Macintosh 
* series of computers.*/ 
/* Earle R. Horton. 
* Wednesday, November 30, 1988 
* All rights reserved. */ 
$include <Windows.h> 
include «Events.h» 
Sinclude «Dialogs.h? 
Sinclude «Fonts.h? 
Sinclude ‘Memory .h> 
Sinclude «Resources.h? 
8include «ToolUtils.h» 
Sinclude «Errors.h»? 
$ include «0SUtils.h? 
include «Desk.h» 
include "dmp-110.h^ 
Sinclude “compat .h" 
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def ine —SEG_ Main 


/* Use our own names for these. */ 
Sdefine storage 1GParam! 
Sdefine pagenum 1GParam2 

8def ine PREC 1GParam3 
Sdefine picture 1GParam4 

/* Useful constants */ 

зде? ine SERRESET 8 

Sdef ine SERSHAKE 10 


def ine XONCR CCchar 2172 
def ine XOFFCR CCchar 219) 
"define RESFILEID — (-8192) 


OSErr SPOpen(); 


Sdefine WNETrapNumber 0х60 

Sdefine UnImpTrapNumber 0х9? 

/* Abort printing if command ”.” pressed. */ 
checkabor tC) 


EventRecord myevent; 
Boolean result; 
Boolean WNEisThere = NGetTrapAddress(WNETrapNumber, 1) != 
NGetTrapAddress(UnImpTrapNumber, 1); 
if CWNEisThere){ 
result = WaitNextEventCeveryEvent, &myevent, ØL, OL); 
)else ( 
SustemTask(); 
result = GetNextEvent(keuDownMask|autoKeuMask, &myevent); 


1f(result)( 
1f(LoWord(muevent.message & charCodeMask) == ‘.’ && 
(myevent modifiers & cmdKey) X 
PrSetError(CilOAbortErr); /* iPrAbort? */ 


) 


This function returns a pointer to a specialized GrafPort 
(a TPrPort) customized for printing. 

Based on passed Print Record, prepare a GrafPort for use 

by application in printing. store information of use to 

us in lGParem[n] fields of the TPrPort. We use а BitMap 

whose baseAddr contains pointer to a buffer whose size is 
teken from prXInfo field of print record. We define the 

portRect to correspond to prinfo.rPage field of the print 
record. Later, will scale application’s drawing commands 
to fit into prInfoPT.rPage Rect, and print Picture which 

the application has created. */ 


~ че? 
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pascal TPPrPort myPrOpenDocChPr int, pPrPort,pIOBuf ) 


THPr int hPr int; 
TPPrPort pPrPort; 
C pIOBuf ; 
TPPrPort thisport; 
Handle uS; 

THPr int savePr int; 
BitMap mybits; 
THPr int ourPr int; 


DCtlHandle d; 
DPstorage s; 
SysEnvRec World; 
short refnum; 
/* Allocate storage, abort if no space for TPrPort. 
* First stage aborts if not enough for a TPrPort, setting 
ж PrError() to memFullErr and returning nil. */ 
if(pPrPort == nil)( 
if(Cthisport = CTPPrPort) 
NewPtr((Size)sizeof(TPrPort))) == nilX 
PurgeMem(maxSize); 
thisport = (ТРРгРогі )NewPtr( (Size sizeof (TPrPort)); 
if(thisport == nil 
PrSetError(memFullErr); 
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return nil; 


) 
thisport->fOurPtr = TRUE; /* TRUE: printing code. */ 


) else ( 
thisport = pPrPort; 


thisport-»fOurPtr = FALSE; /* FALSE: application. */ 


thisport-»fOurBits = TRUE; 
/* If we get here, there is enough space for least TPrPort. 
* next block of code attempts to allocate dynamic storage 
we will need during printing. If it fails, it sets 


application should detect the print error condition, and 
call PrCloseDoc. 
Successfully is disposed of by PrCloseDoc. Storage 
is allocated in several blocks rather than single big 
block in order to facilitate changing size of the output 
* buffer or band. */ 

thisport-»storage = (long)(s = 
CDPstorage )NewP tr ((Size sizeof (Dstorage))); 
1f(s != nil)( 

memset(s,0,sizeof (Dstorage)); 

s-yobuf = NewPtr((Size)2000); 
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ourPrint = hPrint; 
1fCHandToHand(&ourPr int) == noErr X 
thisport-»PREC = Clong)ourPrint; 
Jelse{ 
thisport-»PREC = nil;) 
thisport-»gPort.portBits.baseAddr = mybits.baseAddr = 
NewPtr( (Size) 


CC¥hPrint)-»prXInfo. iRowBytes*(*hPr int) prXInfo. iBandV)); 


С (thisport->storage == nil) || 
(s->obuf == nil) || Cthisport-»PREC == nil) || 
(ngbits.baseAddr == nil) X 
PrSetError(memFullErr); 
Jelse( 

/* If we get here, then memory worries are over, except of 
* course if we run out while defining a pict. Don’t know 
* what happens then. TPrPort is ready to be initialized, 

* and serial port to be opened. Only possible fatal error 
* remaining is а serial port error.*/ 


OpenPort(thisport); 

SetStdProcsC&thisport-»gProcs); 
for this port. */ 

thisport->gPort .grafProcs = &thisport-»gProcs; 

SetPortCthisport); 

SysEnvirons( 1, &Wor ld); 

PrSetError(CSPOpenCs, &Wor1d)); 


/* Fill out gProcs 


/* Save our copy of Print Record Handle, then open port. */ 
thisport-»PREC = Clong2ourPr int; 


/* Define the port’s BitMap as our printing band.*/ 
mybits.bounds.top = 0; 
mybits.bounds. left = 0; 
mybits.bounds.bottom = (*hPrint)->prXInfo.iBandV; 
mubits.bounds.right = (*hPrint)->prXInfo. iBandH* 1; 
mybits.rowBytes = (*hPrint)-»prXInfo. iRowBytes; 
SetPortBitsC&mybi ts); 


MovePortToCC*hPr int) prInfo.rPage.left,C*hPrint)- 
»priInfo.rPage.top); 
Por tSize((*hPr int) prInfo.rPage.right-C*hPr int )- 


»priInfo.rPage.left, (*hPrint)->prinfo.rPage.bottom-C*hPr int )- 


»prinfo.rPage. top); 


RectRgn( thisport-» gPort.visRgn, &thispor t- 
»gPort .por tRect); 

RectRgnCthisport-?gPort .clipRgn, &thispor t- 
»gPort.portRect); 
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thisport->»storage to nil, & sets PrError() to memFullErr. 


Dynamic storage which was not allocated 


thisport->pagenum = 1; 
thisport->storage = Clong)s; 
1f(C*ourPrint)->»prdob.pIdleProc == nil) 
CXourPrint)-»prdob.pIdleProc = 
CProcPtrOcheckabort; 


/* Attempt to save Print Record in ‘PREC’ 1 in printer f ile. 


* No big deal if failure, since it is not essential to 
* printing. */ 
savePrint = (THPrint)GetResource( ‘PREC’, 1); 
if(savePrint != nil 
LoadResource(savePr int); 
**savePrint = **ourPrint; 
ChangedResource(savePr int); 
UpdateResF i leCHomeResF i leCsavePr int )); 


) 
return thisport; 


/* Called at completion of print job, whether successful or 


* not. Clean up any dynamic storage which requires it, then 


* set print error to noErr. */ 
pascal void myPrCloseDoc(pPrPort) 
TPPrPort pPrPort; 

( 


DPstorage s; 
ifC СрРгРогі != nil) && 
(Cs = (DPstorage)pPrPort-»storage) != nil) && 
(s-obuf != nil) &&CpPrPort—PREC != nil) && 
(pPrPort-»gPort.portBits.baseAddr != nil) )( 
/* Assume successful open. */ 
ClosePort(pPrPort); 
PBC lose(&s-> iopb, FALSE); 


) 
ifK(pPrPort != nil)( /* Dispose storage which needs it.*/ 


1f(s != nil)( 
if(s—obuf != nil)( 
DisposPtr(s-,obuf); 


DisposPtr(s); 


1f(pPrPort->PREC != nil)( 
DisposHandleCpPrPort-?PREC),) 

1fCpPrPort-»gPort.portBits.baseAddr != пі1Ҳ 
DisposPtr(pPrPort-?gPort .por tBits.baseAddr ); 


1fCpPrPor t-> fOurP tr { 

DisposPtr(pPrPort);) 

PrSetError(noErr ); /* No bad feelings! */ 

/* routine opens а new page. Check for valid TPrPort, then 

* just start a new picture definition. */ 

pascal void myPrOpenPage(pPrPort ,pPageFrame ) 

TPPrPort pPrPort; 

TPRect pPageFrame; 


Rect *scalerect; 
if(pPageFrame != nil dX 
scalerect = pPageFrame; 
Jelse{ 
scalerect = &pPrPort-»gPort.portRect; ) 
SetPort(pPrPort); 
/* app. may run out of memory while the picture is being 
х saved. Don't know how to prevent or even detect this. */ 
pPrPort- picture = (long)OpenPicture(scalerect); 


/* This is the routine which does the actual printing. 
* Close picture for the page. Use DrawPicture() to draw 
* repeatedly, while moving BitMap down the page to capture 
* an image for each band. 
* Send each band to the output conversion routines. */ 
pascal void myPrClosePage(pPrPort) 
po pPrPort; 
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PicHandle thepic; 
short i, iocount, vband,nbands, rows ,nlef t; 
Весі savepr,scaleRect, savebm; 
long width, height; 
THPrint ourPrint; 
char formfeed; 
DPstorage S; 
ourPrint = CTHPrint)pPrPort-»PREC; /* Set up vars. */ 
SetPortCpPrPort); 
ClosePicture(); 
thepic = (PicHandle)pPrPort->picture; 
vband = (*ourPrint)-»prXInfo. iBandV; 
nbands = (*ourPrint?-»prXInfo. iBands; 
s = (DPstorage )pPrPor t->storage; 
if(PrError() != noErr X 
) else if(setjmp(s-»abortbuf) != ØX 
on abort or error. */ 
PrSetError(il0Abor tErr );) 
else if (pPrPort->pagenum < (*ourPrint)->pruob. iFstPage X/ 
* Check page no. */ 
pPrPort-»pagenum**; ) 
else if(pPrPort-»pagenum** > C*ourPrint2- 
»prJob. iLstPage ){ 
PrSetError¢il0Abor tErr ); 
) else ( 
savepr = pPrPort-,gPort.portRect; 
savebm = pPrPort->gPort.portBits.bounds; 


/* Pops back here 


/* Enlarge portRect of Printing Port. */ 
OffsetRectC&pPrPort-»gPort .portBi ts .bounds, - 

savebm. left,-savebm. top); 
scaleRect = C*ourPrint2-»prInfoPT.rPage; 
OffsetRectC&scaleRect,-scaleRect. left,-scaleRect . top); 
pPrPort-»gPort.portRect = scaleRect; 
RectRgn(CpPrPort-?gPort .visRgn, &scaleRect); 
RectRgn(pPrPort->gPort.clipRgn, &scaleRect); 


rows = scaleRect.bottom - scaleRect. (ор; 
1f((*ourPrint)-»prStl.feed != feedCut || wait- 
nextpage( )){ 
for i=0; i<rows; i+=vband){/* Loop over bands. */ 
MovePortTo(scaleRect.left,-i); /* to next.*/ 
EraseRect(&scaleRect); 
DrewPictureCthepic,&scaleRect?; 
/* Draw in the band. */ 
dumpbitsCpPrPort);/* Print it. */ 


formfeed = 12;/* formfeed. Device Dependent. */ 
s-»iopb.ioPeram.ioReqCount = 1; 

5-2 iopb. ioParam. ioBuffer = &formfeed; 

asyncwr iteCs, CKCCTHPr int )pPrPor t-» PREC ))- 

»prdob.pidleProc); 

/* Restore portRect so Application can drew іп it.*/ 
pPrPort-»gPort.portBits.bounds = savebm; 
pPrPort-»gPort.portRect = savepr; 
RectRgnCpPrPor t-? gPort . visRgn, &savepr 2; 
RectRgnCpPrPort-? gPort . c1 ipRgn, &savepr 2; 


)eise( 


PrSetErrorCilOAbortErr?; /* iPrAbort? */ 


) 
KillPictureCthepic?; 


) 

dumpbits(pPrPort) /* Dump printing band to serial port. */ 
TPPrPort pPrPort; 

( 


DPstorage s; 

int i,rows; 

BitMap *bits; 

ProcPtr idle; 

s = (DPstorage)pPrPort-?storage; 

bits = &pPrPort- gPort .portBits; 

rows = bits-? bounds .bottom-bits-?bounds. top; 
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idle = (*CCTHPrintopPrPort-? PREC ))->»prJob.pIdleProc; 

for (i20; i<rows; 1+= 16 
bitmap_to_hires(s, bits, i,rows-i, idle); 
ifK(PrErrorC) != noErr return; 


) 

/* bitmap_to_hires() 

function translates a QuickDraw BitMap to codes which mau 

be sent to a Tandu DMP-110 dot-matrix printer in 

high-resolution graphics mode. Graphics codes for this 

printer in hi-res mode include all eight bit characters. 
There are two characters for each column of 16 dots on 

paper. The top dot (1) corresponds to bit 

zero of the first bute sent. The bottom dot (16) 

corresponds to bit eight of second bute. There are 960 

columns, 1920 butes, of graphics data to be sent for one 
line of graphics output. Note that the ToolBox bit 

manipulation routines use lower-to-upper bit order. 

No smərts in routine, the whole 1918 butes are sent for 
* each line.*/ 

bitmap_to_hires(s,b,row,nleft, idle) 

DPstorage s; 
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BitMap *b; /* BitMap to print. */ 
int row; /* Starting row on this pass. */ 
int nleft; /* Max number of rows to print. */ 


ProcPtr idle; 


short *obytes, *inbytes; 
int column, lestcol,nbits,dot; 
obytes = (short *)s-)obuf; 
for(dots960;dot- 20; Х obytes(dot] = 0;) 
lastcol = b-»bounds.right - b->bounds. left; 
lastcol = Clastcol > 959) ? 959 : lastcol; 
inbytes = (short *)(b->»baseAddr + b->rowBytes*row); 
nbits = b->rowBytes*8 ; 
for(column=8;column<lastcol;column++X 
(*idle)(); 
if(PrError() != noErr Yeturn; 
for(dotz0;dot«8 && dot«nleft;dot**X 
if(BitTstC inbytes, Clong)(column+dot*nbits))X 
BitSetCobytes, (long )(7-dot))) 


) 
for(dotz8;dot«16 && dot < nleft;dot**X( 
1fCBitTstCinbytes, (long )Ccolumn+dot*nbits))X 
BitSetCobytes, (long )(23-dot))) 


obytes**; 


) 
output hires. detaCs, Clong)Clastcol), idle); 
/* Send to printer. */ 


/* output-hires.data() - Send a stream of high resolution 
х graphics data to the Tandy DMP-110. The codes for 

* transferring the graphics, and for high-resolution paper 
* advance, are hard-coded into this routine. Skips blank 
* graphics codes, and repositions the printer head. The 
* overhead is 8 bytes for repositioning the head and 

* restarting high resolution graphics. If there are four 
* blank columns, then, we break even. If more, we 
* win. If there are less four blank columns, we lose.*/ 

output_hires_data(s, columns, idle) 

DPstorage s; 

long columns; 

asa idle; 


unsigned char содеѕ [10]; 

short *p; 

short pos,ncodes, start; 

short *buf = (short *)s->obuf; 

f or(pos-£,ncodes- ,p-buf ,start-0;pos«960;pos** X 

if(buf [pos] == 0)( 
if(ncodes != 0)( 

sendcodes(s,p,ncodes,start,idle); 
if(PrError() != noErr return; 
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ncodes = 0; 


Jelse( 
if(ncodes == 0)( 
p = &buf [pos]; 
start = pos; 


псодеѕ++; 


) 
if(ncodes != 0)( 
sendcodes(s,p,ncodes,start,idle); 


codes(@] = 26; /* DMP-110 carriage return. 
codes[1] = 27; /* High res line feed. */ 
codes[2] = 'G’; 


S-) iopb. ioParam. ioReqCount = 3L; 
s-?iopb.ioParam.ioBuffer = (Ptr codes; 
asyncwrite(s, idle); 


sendcodes(s, buf ,n,pos, idle) 
DPstorage s; 

char *buf; 

int n,pos; 

ProcPtr idle; 


unsigned char codes[]19]; 


codes[0] = 27; 
codes[1] = 16; 
codes{2] = (ро$››8)&3, 
codes[3] = pos & OxFF; 
codes[4] = 27; 
codes[5] = 73; 
codes[6] = (n>>8)&3; 


codes[7] = n&@xFF; 
S-?iopb.ioParam.ioReqCount 
s-?iopb.ioParam.ioBuffer = 
asyncwr iteCs, idle); 
S-) iopb. ioParam. ioReqCount 
S-) i0pb. ioParam. ioBuffer = 
asyncwrite(s, idle); 


= BL; 
(Ptr )соаеѕ; 
= (long)(2*n); 
buf ; 


/* Modal dialog box: “Insert next sheet.” */ 
wai tnextpage( ) 


DialogPtr sheetdialog; 
WindowPtr tempport; 

short — itemhit,donetupe; 
Handle doneitem; 

Rect donebox; 


if(Csheetdialog = GetNewDialogCSHEETDIALOG, @L,(WindowPtr) 


-1)) == nil) 
return FALSE; 
InitCursor(); 


GetDItemCsheetdialog,DONEITEM, &done type, &done i tem, &donebox ); 


GetPortC&temppor t); 
SetPort(sheetdialog); 

PenSize(3,3); 

InsetRect(&donebox, –4,-4); 
FrameRoundRect(&donebox, 16, 16); 
ModalDialog(OL,&itemhit); 
DisposDialog(sheetdialog); 
SetPort(tempport); 

if(itemhit == STOPITEM) return FALSE; 
return TRUE; 


/* Open serial drvr & configure it. 
OSErr SPOpen(s, World) 

register DPstorage s; 

SysEnvRec — *World; 

( 


register ParmBlkPtr pb; 
int serconf ig; 
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х/ 


Quit if ioResult field 
* of parameter block ever becomes other than noErr. */ 


Pfg settings; 

OSErr error; 

extern char AOutName[ 1, BOutName[ ]; 

extern short BaudRates[ ]; 
error = noErr; 
settings = (Pfg)(GetResource( ‘HEXA’, RESF ILEID22; 
if(settings == пі1){ /* Where's our stuff? */ 

return ResError();} 

LoadResource(settings); 
HNoPurge(settings); 
pb = &5-› iopb; 


switch (pport)( /* get the correct port */ 


case 0: /* modem port */ 
pb-? ioParam. ioNamePtr = C(StringPtr )A0utName; 
break; 

case 1: /* printer port */ 
{fC IsMPPOpen(){ 


CvoidStopA ler tCATALKALERT,nil); 

return portInUse;) 
pb-?ioParam.ioNamePtr = (StringPtr2BOutName; 
break; 


) 
PBOpen(pb,FALSE); 
if (pb-> ioParam.ioResult != noErr X 
return(pb-? ioParam. ioResult);) 
ро-› іоРагат. іоМәпеРіг = nil; 
/* Set up io parameter block for writing to serial driver. 
* a control call resets the baud rate. 
* Another sets flow control. */ 
((CntrlParam *)pb)->»csCode = SERRESET; 
serconfig = data8 + noParity + stop20; 
serconfig += BaudRates[pbaud]; 
(COntr 1Param* pb )-› сѕРагат(0] = serconf ig; 
PBControl(pb, FALSE); 
if (pb-> ioParam.ioResult != noErr) return(pb- 
› ioParam. ioResul t); 
8def ine shake ((SerShk *)&CCOntr 1Param* pb )-> сѕРагат(01) 


shake->errs = FALSE; 
shake->evts = FALSE; 
shake-»fDTR = FALSE; 
shake-?fInX = FALSE; 


1 (XonXoff && CWorld->machineType >= envMachUnknown) X 
ѕһаке-› ҒХОп = TRUE; 
shake->fCTS = FALSE; 
shake->x0n = XONCR; 
shake-?xOff = XOFFCR; 

) else ( 
shake-) fX0n 
shake-»fCTS 


- FALSE; 

= TRUE; 
(CCntrlParam *)pb)-»csCode = SERSHAKE; 
PBControl(pb, FALSE); 
if (pb-> ioParam.ioResult != noErr) return(pb- 

› ioParam. ioResult); 
pb-?ioParam.ioPosMode = 0; 
pb->ioParam.ioPosOffset = 
ReleaseResource(settings); 
return(noErr); 


0; 


/* Routine to write asunchronouslu to serial port, run ап 
x idle proc.idle routine may call PrSetError(), 

* so we check PrError() for abort each time. 
* serial port IO if abort detected. */ 

asyncwr ite(s, idle) 

DPstorage s; 

oe idle; 


IOParam *p = &С5-› iopb. ioParam); 
рн /* Issue ASYNC write. */ 
do 
(*idle)(); /* Idle til done. */ 
if(PrError() != noErr)( /* Check for abort. */ 
if(p->ioResult > 04 /* More chars? */ 
PBKilllIOCp,FALSE); /* Stop output. 


Kill pending 


*/ 
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) 

longjmp(s-? abor tbuf , 1); /* Get out. */ 

)uhile(p- ioResult > 0); 

If(p-> ioResult < ØX 
longjmp(Cs-?abortbuf , 1); 


/* Check for complete. */ 
/* Serial port Error! */ 


) 


Listing: pdef4.c 

/* Code to implement Printing Dialogs. Described in rather 
* complete fashion in Technical Note 895. */ 
/* This file is part of the DMP-110 printer driver for the 
* Macintosh series of computers. */ 

/* Earle R. Horton. 
* Wednesday, November 30, 1988 
* All rights reserved. */ 

Sinclude «Windows.h? 

*include «Events.h? 

Sinclude «Dialogs.h? 

include «Controls.» 

include «Lists.» 

Sinclude «Fonts.h» 

“ілсімде «Memory.h? 

*include «Resources.h? 

8include «ToolUtils.h» 

Sinclude «Packages.h? 

%include «Menus.h? 

Sinclude “dmp-110.h” 

Sinclude “compat .h” 


/* The Pascal Interface to MPW C 2.0.2 does not fully include 


the List Manager. */ 

Sifdef macintosh 

pascal void LGetCellCPtr,short *,Cell,ListHandle); 
pascal void LSetCellCPtr,short,Cell,ListHandle); 
pascal void LSetSelect(Boolean, Cell,ListHandle); 
Rendif 


ifndef iDevDaisy 

Sdefine bDevDaisy 2 

Sdefine iDevDaisy (bDevDaisy << 8) 

#endif 

Sdefine STYLEDIALOG (0хЕ000) 

Sdefine JOBDIALOG (0xE001) 

def ine XTRA 24 /* Six extra longs for our use. */ 
Sdef ine NORMALPRINT 0 

def ine DLGSIZE ((long)(sizeof (TPrD1]g) + XTRA)) 
Sdefine extra(tp,i) (* CClong *)X(char *)(tp) + 

sizeof (TPrD1g)) + (1222 

Sdefine TPSIZE ((long)(sizeof (TPrint))) 

/* Items we handle in the job and stule dialogs. */ 
Sdefine CANCELITEM 2 

Sdefine STYLETITLE 4 

Sdefine STYLELIST 5 

Sdefine ALLBUTTON 5 

def ine RANGEBUTTON 6 

def ine FROMNUM T 

Sdefine ТОМОМ 9 

Sdefine COPIES 11 

Sdefine FANBUTTON 13 

Sdefine SHEETBUTTON 14 

"ifdef MPU68000 /* Aztec does not yet do prototypes. */ 
pascal void CallItemProc(2); 

pascal TPPrD1g CallDigInit(2; 

else 

pascal void CallItemProc(tp,itemhit,RealAddr) /* Glue. */ 
ТРРг019 tp; 


short itemhit; 
ProcPtr RealAddr; 
extern; 


pascal ТРРг019 CallDlgInitChPrint,RealAddr) 
THPr int hPr int; 

ProcPtr RealAddr; 

extern; 


/* Glue. */ 
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tendif 

/* Velidate/update a print record. */ 
pascal Boolean MyPrValidateChPr int) 
THPrint hPrint; 


( 
THPrint thedefault; 
1f(Valid(hPrint)) return FALSE; 
else ( 
thedefault = CTHPrint)(GetResource( 'PREC^,NORMALPRINT22; 
LoadResource(thedefault); 
**hPrint = **thedefault; 
return TRUE; 


/* Printing dialog supervisor function. 

* Ref: Macintosh Technical Note 95. */ 
pascal Boolean MuPrD1gMain(hPrint,pD1gInit) 
THPrint hPrint; 

"did pDigInit; 


ТРРг019 tp; 

WindowPtr tempport; 

short — donetype, itemhit; 

Handle doneitem; 

Rect donebox; 

ProcPtr itemproc; 
tp = CallDigInitChPrint, pDigInit); 
itemproc = tp-?»pItemProc; 
tp->fDone = FALSE; 
tp->fDoIt = FALSE; 
GetPor t(&temppor t); 
SetPort(tp); 
ShowW indow( tp); 
GetDI temC tp, DONEITEM, &done type, &done i tem, &donebox); 
PenSize(3,3); 
InsetRect(&donebox, -4, -4); 
FrameRoundRect(&donebox, 16, 16); 
PenSize(1, 1); 
while(! (tp-> fDone) 

ModalDialog(tp->pF1trProc, &itemhit); 
CallltemProcCtp, itemhit, itemproc); ) 

SetPortCtempport); 
CloseDialog(Ctp2; 
DisposPtr(tp); 
if(tp>fDoIt) (voidoMgPrValidateChPr int); 
return(tp->fDolt); 


) 

/* Default item filter for print dialogs.*/ 
pascal Boolean MyFilter(Ctp, theEvent, itemhit) 
TPPrD1g tp; 

EventRecord *theEvent; 

short *itemhit; 


char c; 
if(theEvent->what == keyDown Х 
C = (theEvent->message & charCodeMask); 
1fC Cc == ІЗ) || (с == 3)X /* Return or Enter. */ 
*itemhit = 1; 
return TRUE; 


) 
return FALSE; 


) 

/* Stule Dialog Filter. Give it to List Manager if it is 
х in list of ‘PREC’s. Signal done if a double-click in а 
* cell. Otherwise, handle via the normal filter.*/ 

pascal Boolean MyStlFilterCtp, theEvent, itemhit) 

ТРРг019 tp; 

EventRecord *theEvent; 

short *itemhit; 


1fC(*itemhit == STYLELISTX 
GlobalToLocal(&theEvent->where); 
Cvoid LClick( theEvent-> where, theEvent- 


© The Best of MacTutor, Vol. 5 


»modifiers, CListHandle JextraCtp,@)); 
LocalToGlobal(&theEvent-> where); 
return FALSE; 

Jelse( 
return MyFilterCtp, theEvent, itemhit); 


/* This function fills a print record with defaults. The 
* default values are stored in Printer resource file, in 
ж PREC 0. This is easy. */ 

pascal void MyPrintDefaul tChPr int) 

THPrint hPrint; 


( 
THPrint thedefault; 
thedefault = CTHPrint)(GetResource( ‘PREC’ ,NORMALPRINT)); 
LoadResource(thedefault); 
**hPrint = **thedefault; /* What the hey. */ 
/* The next routine handles the style dialog. Two 
* possibilities exist. If the cancel button is hit, then we 
* signal quit. The print record is not changed. 
* If “OK” button is hit, then we have to fill in the new 
* style in the user print record. */ 
pascal void HandleStyleltems( tp, itemhit) 
TPPrD1g tp; 
short  itemhit; 


short — thenum, type; 
Handle item; 
Rect box,bigbox; 
MenuHandle PRECMenu; 
long restype; 
short resid; 
short nitems, i; 
THPrint rPrint; 
char thestring[256]1; 
Point theCe11; 

switch(itemhit){ 

case DONEITEM: 
SetPtC&theCe11,0,0); 

LGetSelectCOxFFFF , &theCe11, CListHandleDextraCtp, 022); 


- 255; 
LGetCellC&thestringL 11, &i, theCe11, CListHandleDextraCtp, 022; 
thestring(@] = i; 
rPrint = 
CTHPr int JGetNamedResource( ‘PREC’, thestring); 
if(rPrint == nild{ 
rPrint = (THPrint)GetResource( ‘PREC’ ,8); 


LoadResource(rPr int); 
C*Ctp->hPrintUsr))->prinfo = C*rPrint)->prinfo; 

(*Ctp->hPrintUsr ))->prinfoPT = (*rPrint2- prInfoPT; 

C*Ctp->hPrintUsr ))->»rPaper = (*rPrint)-rPaper; 

(*Ctp->hPrintUsr))-»prStl = C*#rPrint)-»prstl; 
(¥Ctp->hPrintUsr))->prXInfo = C*rPrint)-prXInfo; 
C(*Ctp->hPrintUsr ))->printX(@] = (*rPrint)-)printX[0]; 

LDisposeCC(ListHandleDextra(Ctp,0)); 

tp->fDone = TRUE; 

tp->fDoIt = TRUE; 

break; 
case CANCELITEM: 

LDisposeCCListHandleDextraCtp,22); 

tp->fDone = TRUE; 

tp-?fDoIt = FALSE; 

break; 
default: 

break; 


) 


/* Sumbolic constants used to make LNew() more readable. */ 


8def ine Drawn OxFFFF 
Sdefine noGrow 0x0000 
8def ine noHScrol1 0x0000 
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define vScrol] 
Sinclude <strings.h> 
/* User item for putting up list of available Print Recs. */ 
pascal void PRECuserItemCtp, thei tem) 

ТРРг019 tp; 

short theitem; 


OxFFFF 


short type,i,j,nitems, id; 

Handle item; 

Rect listbox, dataBounds; 

Point cellSize, theCe11; 

char thestring[256]; 

THPrint rPrint; 

long restype; 

ListHandle PRECList; 

/* First time called, create the list. */ 

1 Кехіга(ір,0) == nil)( 
GetDItemCtp, theitem, &type, &i tem, &listbox); 
listbox.right -=15; 
SetRectC&dataBounds, 2,0, 1,0); 
SetPt(&cellSize,0,0); 

PRECList = 

LNewC&1listbox,&dataBounds, cellSize,9, (WindowPtrOtp, 

Drawn,noGrow,noHScro11, vScro11); 
C*PRECList)->selFlags = lDoHAutoscroll + 10nlyOne; 
extra(tp,0) = Clong)PRECList; 

/* Read in the resources, put the nemes in the list. */ 
nitems = CountResources( ‘PREC’); 
(voidOLAddRow(nitems,0,PRECL 150; 
forCiz0,j-0; i**«nitems; X 

rPrint = (THPrintoGetIndResource( ‘PREC’, i); 
GetResInfo(rPrint,&id,&restype, thestr ing); 
SetPtC&theCe11,0, j++); 

LSetCellC&thestr ingL 11, CShort)thestring(21, theCe11, PRECList); 

146C(((*tp-bhPrintUsr))->bprintX[0] == idX 
LSetSelect(0xFFFF,theCel1l1,PRECList); 
LAutoScroll(PRECList); 


) 


/* After the first time, just frame item’s Rect, and call 
* LUpdate() to draw the list. */ 

GetDItemCtp, theitem,&type, &item,&listbox2; 

InsetRect(&1listbox,-1,-1); 

FrameRect(&listbox); 

LUpdate( tp- 
yD]g.window.port.visRgn,(ListHandleJextra(tp,0)); 


/* The stule dialog initializer. Get the dialog from the 
* resource file, calculate Rect for Print Record list. */ 

pascal TPPrD1g MuPrStlInit(hPrint) 

THPrint hPrint; 


( 

TPPrD1g tp; 

short tupe; 

Handle item; 

Rect box, listbox; 
tp = CTPPrD1g)NewPtr(DLGSIZE); 
C(GetNewDialogCSTYLEDIALOG, tp, CWindowPtr )-1)); 
GetDItemCtp, STYLETITLE, &type, &i tem, &box ); 
listbox. left = box.right*20; 
listbox.top = tp-»Dlg.window.port.portRect . top* 10; 

listbox.bottom = tp->Dlg.window.port.portRect .bottom- 10; 

listbox.right = listbox. left + 200; 
GetDItemCtp, STYLELIST, &type, &i tem, &box); 
SetDI temC tp, STYLELIST, type, PRECuserI tem, &listbox); 
extra(tp,0) = nil; 
tp-»pFltrProc = (ProcPtroMyStlFilter; 
tp->»pItemProc = (ProcPtr )HandleStylel tems; 
tp-^hPrintUsr = hPrint; 
return(tp); 


pascal Boolean MyPrSt1DialogChPrint) 
style dialog. */ 


/* Conduct printer 
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THPrint hPrint; (GetNewDialogCJOBDIALOG,tp,(WindowPtr)-1)); 
pushradiobutton(tp, ALLBUTTON, ALLBUTTON, RANGEBUTTON); 


return(KMyPrD1gMainChPr int, MyPrStlInit2); 1fC C*hPrint)-»prSt1.feed == feedCut) 
pushradiobutton( tp, SHEE TBUTTON, FANBUTTON, SHEETBUTTON); 
/* Record user choice of paper feed, page numbers, and else 
* number of copies. */ pushradiobuttonCtp,FANBUTTON, FANBUTTON, SHEETBUTTON); 
pascal void HandleJobI tems( tp, itemhit) GetDI temC tp, FROMNUM ,&thenum, &the item, &thebox ); 
ТРРг019 tp; thenum = (*hPrint)->prudob. iFstPage; 
short itemhit; NumToS tr ing(Clong)thenum, title); 
SetITextCtheitem, title); 
short thenum; GetDItemCtp, TONUM, & thenum, & thei tem, &thebox2; 
long the long; thenum = (*hPrint)-»pruob. iLstPage; 
Handle поті tem; NumToString(C long) thenum, title); 
Rect numbox ; SetITextCtheitem, title); 
char title(256); GetDI temC tp, COPIES, &thenum, &thei tem, &thebox); 
switchCitemhit)( thenum = ((*hPrint)->prJob.iCopies /*= 1*/); 
case DONEITEM: NumloString((long)thenum,title); 
tp-»fDone = TRUE; SetIText(theitem, title); 
tp->fDoIt = TRUE; tp pFltrProc = (ProcPtr )MyFilter; 
їр-›рІїетРгос = (ProcPtr )HandleJob!I tems; 
if(buttonset( tp, ALLBUTTON)2{ tp-^hPrintUsr = hPrint; 
(*(tp->hPrintUsr ))-»prJdob. iFstPage = iPrPgFst; return(tp); 
(*(tp->hPrintUsr ))-»prdob.iLstPage = iPrPgMax; ) 
}е1зе( pascal Boolean MyPrJobDialog(hPrint) /% Conduct printer job 
GetDItem(tp,FROMNUM,&thenum,&numitem,š&numbox); dialog. */ 
GetlText(numitem,ktitle[0]); THPrint hPrint; 
StringToNum(ktitle[06],&thelong); ( 
(*Ctp->hPrintUsr ))-»prJob. iFstPage = thelong; returnCMyPrD1gMainChPr int, MjPrJobInit2); 
GetDItemCtp, TONUM, &thenum, &num i tem, &numbox); ) 
GetITextC(numiten,&title(01); /* Copy a job subrecord. Update the destination record’s 
Str ingToNumC&title[2],&thelong); * printer information, band information, and paper rect, 
C*Ctp— hPrintUsr22)— prJob.iLstPage = thelong; * based on information in the job subrecord. */ 
) pascal void MyPrJobMergeChPr intSrc,hPr intDst) 
GetDItemCtp,COPIES,&thenum, &numi tem, &numbox ); THPrint hPrintSrc,hPr intDst; 
GetIText(numitem, &title(01); ( 
StringToNunC&t itle[0],&thelong); (*hPrintDst)->priInfo. iDev = C*hPrintSrc)->prInfo. iDev; 
(¥(tp->hPr intUsr ))-»prdob. iCopies = Cshort)thelong; (*hPrintDst)-»prJob = (*hPrintSrc)->prJob; 
if(buttonset( tp, SHEETBUTTON) Ҳ (*hPrintDst)-»prXInfo = C*hPrintSrc)-prXxInfo; 
(*Ctp->hPrintUsr ))->»prStl.feed = feedCut; (*hPrintDst)->rPaper = (*hPrintSrc)->rPaper ; 
C*hPrintDst)->prinfo = C*hPrintSrc)->prinfo; 
«оиа = feedFanfo1d; ) (*hPrintDst)->prInfoPT = C*hPrintSrc)->prinfoPT; 
reak; 
case CANCELITEM: /* Handu test for radio button down. */ 
tp fDone = TRUE; int buttonset(d, num) 
break; DialogPtr d; 
case SHEETBUTTON: short num; 
pushradiobut ton( tp, SHEETBUTTON, FANBUTTON, SHEETBUTTON); ( 
C¥Ctp->hPrintUsr ))->prStl.feed = feedCut; short уре; 
break; Handle item; 
case FANBUTTON: Rect box; 
pushradiobuttonCtp,FANBUTTON, FANBUTTON, SHEE TBUTTON); GetDI temCd,num, &type, &i tem, &box); 
(*(tp->hPrintUsr ))-»prStl.feed = feedFanfold; 1f(GetCtlValue(item) == 1X 
break; return true; 
case ALLBUTTON: Jelse( 
жары ы а t u а А return false; 
reak; 
case RANGEBUTTON: ) 
pushradiobutton(tp,RANGEBUTTON,ALLBUTTON,RANGEBUTTON); pushradiobutton(thedialog,itemhit,first,last) 
break; DialogPtr thedialog; /* set itemhit, unset */ 
default: int itemhit, first, last; /* all others in range */ 
break; 
int itemtype, i; 
Handle itemhandle; /* Does check boxes, too. */ 
/* Tne job dialog initializer. Make sure all the buttons Rect itemrect; 
* come up reflecting the Print Record contents. */ if(first ==0) return; 
pascal TPPrD1g MyPrJobInitChPr int) forCi=first-1; last-itt; Х 
THPrint hPrint; GetDItemCthedialog, 1,&itemtype, &i temhandle, &itemrect); 
{ ifCi == itemhit) SetCtlValueCitemhandle, 1); 
ТРРг019 tp; else SetCtlValue(itemhandle,0); 
short thenum; ) 
Handle theitem; 
Rect thebox; /* This function answers the question: Can we possibly use 
char title[2551]; * this print record? Try to be liberal here. Don’t 
ір = (TPPrD1g)NewPtr(DLGSIZE); * allow a Print Record which requires a larger buffer than 
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x our printing routines can handle. */ 
int ValidChPr int) 
THPrint hPrint; 


{ 
if (CCC*hPrint)-> iPrVersion != VERSION) || (C*hPrint)- 
^»prInfo.iDev != Ø) || CC*hPrint)-»prJob.bUDocLoop != 
bDraf tLoop)) 
return FALSE; 
1f(C*hPrint)->prXInfo.iBandV != 64 || 
(*hPrint)-»prXInfo. iBandH != 959 || 
(*hPrint)->prXInfo. iRowBytes != 120 
) 


return FALSE; 


return TRUE; 


) 


Listing: PDriver.C 

/* This is the driver. A description of the driver can be 
* found in Device Manager chapter of Inside Macintosh, & a 
* description of THIS driver can be found in Print Manager 
ж chapter .*/ 

/* file is part of the DMP-110 printer driver for the Macin- 
tosh series of computers.*/ 

/* Earle R. Horton. 
* Wednesday, November 30, 1988 

* All rights reserved. */ 

def ine DRIVER 

*include <Windows.h> 

* include <Events.h> 

8$include <Dialogs.h> 

8include «Fonts.h» 

include «Memorg.h» 

*include «Resources.h? 

include (ToolUtils.h» 

Sinclude «Errors.h» 

*include «Desk.h» 

*include “dmp-110.h” 

Sinclude "compat.h" 

def ine . SEG__ Main 

def ine IPrEvtATI OxOOFFFFFD 

Sdefine 1РгЕу{Тор QxQQFEFFFD 

Sdefine dNeedGoodBye 4 

int checkabort(); 

/* Useful constants */ 

8def ine SERRESET 8 

8def ine SERSHAKE 10 

Sdefine XONCR ((char)17) 

дег ine XOFFCR CCchar 219) 

Sdefine RESFILEID — (-8192) 


extern char AO0utName[ 1, BOutName[); 
extern short BaudRates[ ]; 

extern char prifstr(]; 

extern char prinitstr(]; 

extern char prtopstr[]; 

extern char preopstr[]; 

extern char prmargin[]; 

extern char prhireslf(]; 


OSErr openprinterf ileC2, SPOpen(C); 
/* Driver close routine. 
* Close serial port. Dispose of our storage. 
* Better not close the serial driver if we 
* are dealing with 64k ROMs. 
* Called by device manager under UniFinder when application 
* heap is reinitialized.*/ 
OSErr myPrClose(p,d) /* Device Close Call */ 


PrParam *p; /* ==) parameter block */ 
DCtIPtr d; /* ==) device control entry */ 
return(noErr ); 


%include <strings .h» 


© The Best of MacTutor, Vol. 5 


/* Printer driver open routine. Open our printer resource 
* file, get any information we have stored, allocate a 
* non-relocatable block of storage, set up serial port for 
* use. Check errors. */ 
OSErr туРгОреп(р, d) 
PrParam *p; /* = 
DCtlPtr d; /* = 


=> parameter block */ 
=) device control entry */ 


extern short DriverEntry; 
return (поЕгг); 


OSErr mygPrPrimeCp,d) /* We don’t prime. It’s for drivers 
which do */ 
/* read/write directly. */ 


PrParam *p; /* ==) parameter block */ 
DCt]Ptr d; /* ==) device control entry */ 
return(noErr ); 


OSErr myPrControl(p,d) /* Control calls. Many defined, few 
implemented. */ 
PrParam *p; /* = 
DCtIPtr d; /* = 


=> parameter block */ 
-) device control entry */ 


Dstorage storage; 

char *buf = nil; 

SysEnvRec World; 

OSErr error; 

ProcPtr idle; 

SysEnvirons( 1, &Wor 1d); 

PrSetError(noErr); 

memset(&storage,0,sizeof (Dstorage)); 

error = SPOpen(&storage, &Wor ld); 

ifCerror != noErr) return noErr; 

Storage. iopb. ioParam. ioResult = noErr; 

if(setjmp(storage.abortbuf) != ØX 
PBClose(&storage. iopb); 
if(p-^csCode == iPrEvtCt1 Ҳ 

DisposPtr (buf ); 


return noErr; 


/*Device Control Call. p-?csCode gives opcode, and we switch 
on it to perform low-level Printing calls*/ 
switch (p->csCode){ 
case iPrBitsCt]:/* Send a bitmap to the printer. */ 
break; 
case iPrEvtCtl: /* Screen prntng. Ccmd-shift 4.)*/ 
1f(*Cshort*)(&p-> 1Рагат1) == 1X/* Top window. */ 
buf = NewPtr(2000L 5; 
ifCbuf != nild{ 
dumptop(&s torage, buf ); 
DisposPtr (buf ); 


) 
else if(*(short*)(&p- 1Рагат1) == 2X 


/* Screen. */ 
buf = МенРіг(20001 ); 
if(buf != nil)( 
dumpscreen(&storage, buf ); 
DisposP tr Cbuf ); 


) 
break; 


default: 
break; 


PBClose(&storage.iopb); 
return noErr; 


/* Printer driver status call, used by the Font Manager to 


* request а copy of printer? font characterization table. 
* Ignored like the control call. */ 
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OSErr muPrStatus(p,d) /* Device Status Call */ 
PrParam *p; /* ==> parameter block */ 
DCtlPtr d; /* ==) device control entry */ 


return (noErr); 


/* Open serial driver and configure it. Quit if ioResult 
* field of param block ever becomes other than noErr. */ 

OSErr SPOpen(Cs,World) 

register DPstorage s; 

SysEnvRec — *World; 


register PermBlkPtr pb; 
int serconf ig; 
Pfg settings; 
Handle pf ilename; 
short pf ile; 
pfilename = GetResourceC'STR ”,0хЕ000); 
if(pfilename == nil)( 
return ResError(); ) 
HLockCpf i lename); 
pfile = OpenResFile(*pfilename); 
if(pfile == -1)( 
return ResError(); ) 
DisposHandle(pf ilename); 
settings = (Pfg)(GetResource( 'HEXA " , RESF ILEID22; 
if(settings == nil)( 
return ResError(); ) 
LoadResource(settings); 
HNoPurge(settings); 
pb = &5-› iopb; 


switch (pport)( /* get the correct port */ 


case 0: /* modem port */ 
pb->ioParam.ioNamePtr = (StringPtr )A0utName; 
break; 

case !: /* printer port */ 

default: 
1 f CIsMPPOpenc 02 


Cvoid StopAlertCATALKALERT,nil); 

return portInUse; ) 
pb-?ioParam.ioNamePtr = (StringPtr2BOutName; 
break; 


) 
PBOpen(pb,FALSE); 
if (pb-> ioParam.ioResult != noErr X 
return(pb-> ioParam. ioResult); ) 
ро-› ioParam. ioNamePtr = nil; 
/* Set up the io parameter block for writing to the serial 
* driver. a control call resets the baud rate */ 
СССпіг1Рагатм *)pb)-»csCode = SERRESET; 
serconfig = data8 + noParity + stop20; 
serconfig += BaudRates[pbaud]; 
(CCntr 1Param* pb )-› сѕРагат(0] = serconf ig; 
PBControl(pb, FALSE); 
if Срь-› ioParam.ioResult != noErr) return(pb- 
> ioParam. ioResul t); 
8def ine shake ((SerShk *)&((Cntrl]Param*)pb)-,csParam[0]) 
shake-»errs = FALSE; 


shake-»evts = FALSE; 
shake->fDTR = FALSE; 
shake->f InX = FALSE; 


If (XonXoff && (World-»machineType >= envMachUnknown) X 
shake->fX0n = TRUE; 
shake->fCTS = FALSE; 
shake-?xOn = XONCR; 


shake-?xOff = XOFFCR; 
) else ( 

$һаке-›ЇХ0п = FALSE; 

shake->fCTS = TRUE; 


(ССпіг1Рагат *)pb)->csCode = SERSHAKE ; 

PBControl(pb, FALSE); 

if (pb-> ioParam.ioResult != noErr) return(pb- 
› ioParam. ioResul t); 
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ро-› ioParam. ioPosMode = 
pb-? ioParam. ioPosOffset 
return(noErr ); 


0; 
z 0; 


printstring(s,string) /% Send printer control string to */ 
/* serial driver. */ 

register DPstorage s; 

unsigned char *string; 


s->iopb.ioParam.ioBuffer = (Ptr)(string+1); 
S-) iopb. ioParam. ioReqCount = (long)(string[0]); 
asyncwr i teCs, checkabort); 


— aye 
* 


dumptop() - Called to dump the top window to the screen. 
Nothing if top window is a color window. 
Uses PtInRgn() to determine the extent of the window’s 
Structure region, so we can print entire window frame. 
If you know of a better wau, let me know. Question: 

* What do we do if we get a round window? */ 
dump top(s, obuf ) 
DPstorage s; 
short *obuf; 


чем * 


EventRecord myevent; 

GrafPtr tmpport,oldport; 

int i,rows,width, first_row, last_row, left offset; 
Rect printrect; 

GetPor t(&oldport); 

tmpport = (GrafPtr FrontWindow( ); 
SetPortCtmpport); 

/* Expand portRect to Rect enclosing Window struct region. */ 
printrect = tmpport->portRect; 
LocalToGlobalC&printrect); 
LocalToGlobalC&printrect .bottom); 

whi TeCPtInRgn(*(Point* )(&printrect), C(CWindowPeek )tmpport)- 

»strucRgn)){ printrect.left-; ) 
printrect. lef t+t+; 

whileCPtInRgnC*CPoint*)C&pr intrect?, (CWindowPeek )tmpport)- 

>strucRgn)){ printrect.top-;) 
printrect.top**; 
whileCPtInRgnC*CPoint*)C&printrect .bottom), C(CWindowPeek )tmpport)- 

»strucRgn)){ printrect.bottom**;) 
printrect.bottom-; 

whileCPtInRgnC*CPoint*)C&pr intrect .bottom), CCWindowPeek )tmpport)- 

»strucRgn)){ printrect.right++; ) 
printrect.right-; 

GlobalToLocalC&printrect); 
GlobalToLocal(&printrect .bottom); 
/* Calculate rows in BitMap which we need to print. Send 
* sixteen at a time to the BitMap printing routine.*/ 
first.row = printrect.top - tmpport->portBits.bounds. top; 
last_row = printrect.bottom - tmpport->portBits.bounds. top; 
leftoffset = printrect.left - tmpport->portBits.bounds. left; 
width = printrect.right - printrect. left; 
for(i=f irst row; i«zlast row; i+= 16 X 
bitmap_to_hires(s, &tmpport->portBits, i, 
obuf ,width, lef t_offset, last_row-i+1); 


) 
SetPort(oldport); 


/* dumpscreen() - Called to dump the screen to the printer. 
* Dumps WMgrPort instead. Funky stuff if screen is not in 
х two-color mode. */ 

dumpscreen(s, obuf ) 

DPstorage s; 

short *obuf ; 


GrafPtr tmpport; 
int i,rows,width; 
GetWMgrPort(&tmppor t); 
rows = tmpport-?portBits.bounds.bottom - tmpport- 
»portBits.bounds. top; 
width = tmpport->portRect.right - tmpport- 
»portRect. left - 1; 
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for i=0; i<=rows; i+= 16 
bitmap_to_hires(s, &tmppor t- 
i: a URSI K 


М w 
m 


bitmap. to.hiresC) 
function translates a QuickDraw BitMap to codes which may 
be sent to a Tandy DMP-110 dot-matrix printer in 
high-resolution graphics mode. Graphics codes for this 
printer in hi-res mode include all eight bit characters. 
There are two characters for each column of 16 dots on 
paper. The top dot (1) corresponds to bit 
zero of the first byte sent. The bottom dot (16) 
corresponds to bit eight of second byte. There are 960 
columns, 1920 bytes, of graphics data to be sent for one 
line of graphics output. Note that the ToolBox bit 
manipulation routines use lower-to-upper bit order. 
No smarts in this routine, whole 1918 bytes are sent for 
* each line. */ 
bitmap_to_hires(s,b,row,obuf ,width, left_offset,nleft) 
DPstorage s; /* Global driver storage. */ 


3€ 3€ 3 3* 3 39 »* * жым мж 


BitMap *b; /* BitMap to print. */ 

int row; /* Starting row on this pass. */ 
short *obuf; /* Serial port output buffer. */ 
int width; /* Print this many columns. */ 


int left.offset; /* Start this far from left of b- 
 bounds.left. */ 
C тегі; /* Мах number of rows to print. */ 
short *obutes,*inbutes; 
int column, lastcol,nbits,dot; 
f or(dot-960;dot- ›0; Х 

obuf [dot] = 0, 


obytes = obuf; 
lastcol = 
lastcol = Clastcol > width) ? width : lastcol; 
inbytes = (short *)(b-»baseAddr + b->rowBytes*row); 
nbits = b->rowBytes*8 ; 


/* Transform QuickDraw BitMap to Tandy DMP-119 high resolution 


graphics using ToolBox bit-manipulation routines. Sixteen 
rows BitMap column become two-byte printing code. */ 
for(column=lef t_offset;column<=lastcol+lef t_of fset;columnt+X 
for(dot-z0;dot«8 && dot<nleft;dot++X 
If(BitTstCinbytes, Clong)(column+dot*nbits))X 
BitSetCobytes, (long)(7-dot)); ) 


) 
for(dot=8;dot<16 && dot < nleft;dot++X 
If(BitTstCinbytes, Clong)Ccolumn*dot*nbi ts22 X 
BitSetCobytes, Clong2(23-dot )); ) 


obytes*t*; 

output hires.data(s,obuf, Clong2(Clastcol2-1)5; /* Send to 
printer. */ 
/* output. hires. dataC) - Send a stream of high resolution 
graphics data to the Tandy ОМР-110. The codes for 
trensferring the graphics, and for high-resolution paper 
advance, are hard-coded into this routine. Skips blank 
graphics codes, and repositions the printer head. The 
overhead is 8 bytes for repositioning the head and 
restarting high resolution graphics. If there are four 
blank columns, then, break even. If there are more, we 
* win. If there are less than four blank columns, lose. */ 
output_hires_data(s, buf ,columns) 
DPstorage s; 
short *buf ; 
long columns; 


“7” 
зе x MH * ж * м 


short *p; 
short pos,ncodes, start, max; 
max = (columns > 959) ? 959 : columns; 
. for(pos=8, ncodes=0, p=buf , star t=0; pos<=columns; postt+ X 
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(b->bounds.right > 959) ? 959 : b-»bounds.right; 


if(buf [pos] == 0)( 
if(ncodes != 0)( 
sendcodes(s,p,ncodes, start); 
ncodes = 0; } 
}е1зе ( 
if(ncodes == 0)( 
р = &buf [pos ]; 
start = pos; ) 
ncodes**; 


) 

if(ncodes != 0)( 
sendcodes(s,p,ncodes,start); ) 

printstringCs,prhires1f 5; 


sendcodes(s, buf ,n, pos) 
DPstorage s; 

char *buf; 

int n,pos; 

( 


unsigned char codes[10); 
s-»iopb.ioParam.ioBuffer = (Ptr)&codes[0]; 


codes[0] = 27; 
codes[1] = 16; 
codes[2] = (ров»>8 %3; 
codes[3] = pos & OxFF; 
codes[4] = 27; 
codes(5] = 73; 
codes[6] = (n> 8283; 
codes[7] = n&@xFF; 


5-› iopb. ioParam. ioReqCount = 8; 
asyncwrite(s,checkabort); /* Send 8 bytes to printer. */ 
5-› iopb. ioParam. ioBuffer = &buf [0]; 
s-?iopb.ioParam.ioReqCount = 2*n; 

asyncwr iteCs, checkabort); /* Print the buffer. */ 


) 


/* checkabort() - Returns TRUE if command-’.’ detected. 
* Otherwise, FALSE. */ 
checkabort(C) 


EventRecord myevent; 
1f (Wai tNextEventCeveryEvent, &myevent , 01 /*WaitTime*/, 0L) 
1f(LoWord(myevent.message & charCodeMask) == '.' && 
(myevent.modif iers & cmdKeu) X 
PrSetError(Cil0AbortErr ); 
ee TRUE; 


) 
return FALSE; 


/* Routine to write asynchronously to serial port, and run 
* an idle proc while we wait. The idle routine may call 
* PrSetError(), so we check PrError() for abort each time. 
* Kill pending serial port IO if abort detected. */ 

asyncwrite(s, idle) 

DPstorage s; 

ProcPtr idle; 


IOParam *p = &(s-?iopb.ioParam); 
dor pa /* Issue ASYNC write. */ 
do 
(*idle)(); /* Idle til done. */ 
if(PrError() != noErr)( /* Check for abort. */ 
if(p->ioResult > @){ /* More chars? */ 
РВК11110(р,ҒА(5Е); /* Stop output. */ 


longjmp(s-»abortbuf, 1); /* Get out. */ 


)while(p-?ioResult > 0); /* Check for complete. */ 


) 


Listing: DMP-118.rsrc.r 


/* contents of a Macintosh Printer Resource File can be found 
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in the Print Manager Chapter of Inside Macintosh, if you can 


get it. */ 


/* This file is part of DMP-110 printer driver for the Mac 


* series of computers. */ 
8#include "Турев.г” 
/* This file’s creator. */ 
define Version “ОМР- 110 v1.0" 
type ‘Dmp1’ ( 
pstring; /* String */ 


2 
/* Print record resource file copu. */ 
type ‘PREC’ ( 
integer ; /* version */ 
/* prInfo */ 


byte; 
byte; /* iDev */ 
integer ; /* iVres */ 
integer ; /* iHres */ 
rect 3 /* rPage */ 
rect } /* rPaper */ 
/* prSt1 */ 
integer ; /* wDev */ 
integer ; /* iPageV */ 
integer ; /* iPageH */ 
byte ; /* bPort */ 
byte j /* feed */ 
/* prlnfoPT */ 
bute; 
bute; /* iDev */ 
integer ; /* iVres */ 
integer ; /* iHres */ 
rect ; /* rPage */ 
/* prXInfo */ 
integer ; /* iRowButes */ 
integer ; /* iBandV */ 
integer ; /* iBandH */ 
integer ; /* iDevButes */ 
integer ; /* iBands */ 


bute ; /* bPatScale */ 


д 
bute ; /* bUlThick */ 
bute ; /* bU10ffset */ 
bute ; /* bUIShadow */ 
byte ; /* scan */ 
byte ; /* bXInfoX */ 
/* prJob */ 
integer ; /* iFstPage */ 
integer ; /* iLstPage */ 
integer ; /* iCopies */ 
byte ; /* bJDocLoop */ 
byte ; /* fFromUsr */ 
longint ; /* pIdleProc */ 
longint ; /* pFileName */ 
integer ; /* iFileVol */ 
byte ; /* bFileVers */ 
byte ; /* bJobX */ 
array [191( /* “Private” */ 
integer; 


); 

resource ‘ICN®’ (128, "DMP-110^)5 ( 
/* array: 2 elements */ 
/* (1) */ 
$"0000 0000 0000 0000 0000 0000 0000 0000" 
$"0000 0000 0000 0000 0000 0000 OTF 8000" 
$"0040 С000 0040 А000 0040 9000 0040 Ғ800" 
%%0040 0800 0040 0800 0040 0800 0040 0800" 
$"0040 0800 0040 0800 O3FF FFCO 04АА АС20" 
$"0405 55A9 04AA АПАй Ø27F Ғ840 0200 0040" 
$^°01ЕЕ FF80 0008 0400 0008 0400 0008 0400" 
%”1Е08 0Е00 IFFO 1Ғ00 1Е00 1Ғ00 0000 BA’, 

/* [2] */ 

$"0000 0000 0000 0000 0000 0000 0000 0000" 
$"0000 0000 0000 0000 0000 0000 001Ғ 8000" 
$"007F С000 007Ғ Е000 007Ғ FOOD 007Ғ Ғ800" 
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$"007F F800 OO7F Ғ800 007Ғ Ғ800 007Е F800" 
$^007F Ғ800 007F Ғ800 O3FF FFCO O7FF FFE0" 
$“O7FF FFEØ O7FF FFE® 0ЗЕҒ FFCØ 03FF FFCO" 
$°01ЕЕ FF80 0008 0400 0008 0400 0008 0400" 
$^1E08 0600 IFFO 1Ғ00 1Е00 1Ғ00 0000 OA" 


) 

); 

resource ‘FREF’ (128) ( 
‘PRER’, 
0, 

); 

resource 'Dmpl^ (Ø) ( 
Version 


); 
resource 'BNDL^ (128) ( 


‘Dmp 1’, 
( 
ICN’, 
( 
0, 128 
), 
'FREF”, 
0, 128 
) 
) 


); 
data ‘HEXA’ (-8192, “Printer Settings”) ( 
%%0001 0002 0000 " 


; 
resource ‘STR ' (-4092, “Right Button?) ( 
“Modem” 


resource ‘STR ‘ (-4093, “Left Button”) ( 
“Printer” 


) Р 
resource ‘STR * (-4091, “List label”) ( 
“Select Speed and Click on a Port.” 


resource ‘STR ' (-8191, “Spool File Name”) ( 
“Print File” 


resource 'DITL^ (-8191,”Job dialog tempplate”) ( 


(8, 321, 28, 381}, 
Button ( 
enabled, 
“оқ” 
), 
(9, 395, 29, 455), 
Button ( 
enabled, 
“Cancel” 


(6, 6, 23, 127), 

StaticText ( 
disabled, 
Version 


); 

(30, 5, 46, 89), 

StaticText ( 
disabled, 
“Page Range:" 


(30, 93, 45, 138), 
RadioButton ( 
enabled, 
"All? 


), 
(30, 140, 46, 200), 
RadioButton ( 
enabled, 
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“From: ” 


(30, 205, 46, 231), 
EditText ( 
disabled, 
ғ” 


), 
(30, 242, 46, 210), 
StaticText ( 
disabled, 
То” 


), 

(30, 272, 46, 304), 

EditText ( 
disabled, 


), 

(55, 5, 71, 89), 

StaticText ( 
disabled, 
“Соріев:” 


), 

/* [11] */ 

(55, 95, 71, 127), 

EditText ( 
disabled, 
“1” 

), 

(55, 145, 71, 200), 

StaticText ( 
disabled, 
^Feed:"^ 


), 

(55, 205, 70, 303), 

RadioButton ( 
enabled, 
“Continuous” 


), 

(55, 305, 71, 425), 

RadioButton ( 
enabled, 

) “Sheet Feed” 


) 

); 

resource ‘DITL’ (-8192, "Style Dialog Template”) ( 
( 


(44, 390, 64, 450}, 
Button ( 

enabled, 

“ОҚ” 


), 
(10, 390, 30, 450), 
Button ( 
enabled, 
“Cancel” 


J; 

(10, 4, 30, 124), 

StaticText ( 
disabled, 

) *DMP-110 v1.0" 

(37, 66, 53, 120), 

StaticText ( 
disabled, 
*Style:"^ 


), 
(0, 0, 0, 0), 


UserItem ( 
enabled 


i ) 
resource ‘DITL’ (-8190, “Next Page Template”) ( 
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(30, 60, 46, 140), 
Button ( 
enabled, 
“Done” 


), 
(30, 160, 46, 240), 
Button ( 

enabled, 

“Stop” 


(8, 8, 24, 120), 

StaticText ( 
enabled, 
Version 


2 
(8, 120, 24, 265), 
StaticText ( 
enabled, 
“Insert Next Sheet” 


) 
2 
resource ‘DLOG’ (-8191, "Job Dialog”) ( 
(52, 16, 136, 492), 
dBoxProc, 
invisible, 
noGoAway, 
0x1, 
-8191, 
“Job” 
); 
resource ‘ICON’ (-4080, “DMP-1102) ( 
$"0000 0000 0000 0000 0000 0000 0000 0000" 
$"0000 0000 0000 0000 0000 0000 007Ғ 8000" 
%”0040 С000 0040 А000 0040 9000 0040 F800" 
$"0040 0800 0040 0800 0040 0800 0040 0800" 
%%0040 0800 0040 0800 O3FF ҒҒС0 04АА АС20" 
%%0405 55A0 04АА АПАЙ Ø27F Ғ840 0200 0040" 
ФО ІҒЕ ҒҒ80 0008 0400 0008 0400 0008 0400" 
$"1E08 0Е00 IFFO 1Ғ00 100 1Ғ00 0000 BA” ); 
resource 'DLOG^ (-8192, "Style Dialog”) ( 
(30, 20, 113, 488), 
dBoxProc, 
invisible, 
noGoAway, 
9x1, 
-8192, 
«St^ 7, 
resource 'DLOG^ (-8190, “Next Page Box”) ( 
(48, 51, 100, 330), 
dBoxProc, 
=}, 
noGoAway, 
0x0, 
-8 190, 
"Next Page"); 


/* Print Record provides 60 dpi in the printing portRect as 
* seen by application, and scales the image up to 120 dpi. 
* It is useful scaling up BitMaps to double image size, or 
* word processing applications where text justification is 
* needed. */ 

resource ‘PREC’ (0,"Default Scale”) ( 


3, 

0, 

0, 

60, 

60, 

(0, 0, 630, 480), 
(-15, -15, 645, 495), 
512, 

1320, 

1020, 

0, 


1, 

й, 

0, 

120, 

120, 

(2, 0, 1260, 960), 

/* TPrXInfo */ 

120, /* rowButes */ 

64, /* vertical dots */ 

959, /* horizontal dots */ 
7680, /* size of bit image */ 
20, /* bands per page */ 

0, /* bPetScale */ 

1, /* bUIThick */ 
1, /* bUlOffset */ 
1, /* bUIShadow */ 
0, /* scenTB */ 
0, /* unused */ 
1, 
9999, 
1 
0 
1 
0 


0 
0,0, 
0, 
( 0,-1,-1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ) 
7 
/* Тһе printing code puts а сору of the last-used 
* Print Record here. */ 
resource ‘PREC’ C1,"Last Used Print Record”) ( 
д 
0, 
0, 
80, 
80, 
(0, 0, 840, 640), 
(-20, -20, 860, 660), 
512, 
1320, 
1020, 


0, 

120, 

120, 

(2, 0, 1260, 960), 

/* TPrXInfo */ 

120, /* rowButes */ 

64, /* vertical dots */ 

959, /* horizontal dots */ 
7680, /* size of bit image */ 
20, /* bands per page */ 

0, /* bPatScale */ 

1, /* bUlThick */ 
1, /* bUlOffset */ 
1, /* bUIShadow */ 
0, /* scanTB */ 
0, /* unused */ 
1 
9 
1 
1 


й 
999, 
0, 


0,0, 
0,0, 

0, 

( 4,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0) 
); 


/* Print Record causes drawing program to reduce ап object- 
* oriented drawing by 33%, allows us to fit a larger image 
* on a single letter-sized sheet of paper. If application 
х does not check prStl.iPageV and prSt1.iPageH fields, then 
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* results are exactly same as produced by "Exact BitMap.^*/ 
resource ‘PREC’ (2,"Shrink To Fit”) ( 


) 


3, 

0, 

0, 

80, 

80, 

(0, 0, 1280, 960), 
(-20, -30, 1300, 990), 
512, 

1980, 

1530, 


0, 

80, 

80, 

(0, 0, 1280, 960), 

/* TPrXInfo */ 

128, /* rowBytes */ 

64, /* vertical dots */ 

959, /* horizontal dots */ 
7680, — /* size of bit image */ 
20, /* bands per page */ 

0, /* bPatScale */ 

/* bUlThick */ 

/* bUlOffset */ 

/* bUIShadow */ 

/* scanTB */ 

/* unused */ 


ьо “- S&S Ww “м 


ЮО ~ 


99, 


~ 


` ws ~ 
` Мм 


` 


~ — © © © Qe ЮО ,— @ Qe — — 
` 


/* This Print Record reflects the actual size of the printed 
* image in dots. Theres a one-to-one correspondence between 
* screen pixels and printed dots. Best to use for painting 
* programs, but printed image will be smaller than what is 
* seen on the screen. */ 

resource ‘PREC’ (3, “Exact BitMap”) ( 


3, 

0, 

0, 

120, 

120, 

(0, 0, 1280, 960), 
(-20, -30, 1300, 990), 
512, 

1320, 

1020, 


0, 

120, 

120, 

(0, 0, 1280, 960), 

/* TPrXInfo */ 

120, /* rowButes */ 

64, /* vertical dots */ 

959, /* horizontal dots */ 
7680, /* size of bit image */ 
20, /* bands per page */ 

0, /* bPatScale */ 

1, /* bU]Thick */ 
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— “> 


жұмы мж x>- 


* 


1, /* bUlOffset */ 
1, /* bUlShadow */ 
0, /* scanTB */ 

0, /* unused */ 

1, 

9999, 

1, 

0, 

1, 

0,0, 

0,0, 

е 
3,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 


Print Record gives а printing port resolution of 80 дрі, 
which is close to ImageWriter res & therefore close 

to what most Macintosh applications expect to see. The 
problem with this ‘PREC’ is that final image is scaled 

by a non-integral factor, & so text justification in word 
processing programs fails by a few bits width.*/ 


resource ‘PREC’ (4,*Compatible”) ( 


д 
0, 
0, 
80, 
80, 
(0, 0, 840, 640), 
(-20, -20, 860, 660}, 
512, 
1320, 
1020, 


0, 

120, 

120, 

(0, 0, 1260, 960), 

/* TPrXInfo */ 

120, /* rowButes */ 

64, /* vertical dots */ 

959, /* horizontal dots */ 
7680, /* size of bit image */ 
20, /* bands per page */ 


0, /* bPatScale */ 
1, /* bUlThick */ 
1, /* bU10ffset */ 
1, /* bUIShadow */ 
0, /* scanTB */ 

0, /* unused */ 

1, 

9999, 

1, 

0, 

1, 

0,0, 

0,0, 

Т 

) 4,-1,-1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 


); 
NM ‘STR®’ (-4080, "Baud Rates’) ( 


"300", 
“600", 

1200", 
“1800”, 
"2400", 
"3600", 
“4800”, 
"1200", 
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"9600", 
"19200", 
"57600" 


); 


resource 'DITL^ (-4078, “ATalk Items”) ( 
( 


(139, 121, 159, 181), 
Button ( 

enabled, 

“ОК” 
), 
(54, 11, 125, 294), 
StaticText ( 

enabled, 


“This printer cannot use the printer port now “ 
“because AppleTalk is active. 


Please either ” 


“turn off AppleTalk, use the modem port ” 
“instead, or choose another printer." 


), 
(9, 235, 41, 267), 


Icon ( 
enabled, 
-4080 

) 


) 
); 


resource ‘DITL’ (-4079, “5,541 Items”) ( 


(90, 137, 110, 197), 
Button ( 

enabled, 

"OK? 


J; 

(56, 21, 76, 308), 

StaticText ( 
enabled, 


“This Printer requires System 4.1 or newer!” 


), 
(11, 274, 43, 306), 
Icon ( 

enabled, 

-4080 ) 


15 


resource 'ALRT^ (-4079, “Sys4lAlert”) ( 


(40, 36, 164, 370), 
-4019, 
( 


OK, visible, sound], 
OK, visible, soundl, 
OK, visible, sound], 
OK, visible, sound! 
у; 


resource 'ALRT^ (-4078, “ATalk is on!”) ( 


(48, 38, 216, 342), 
-4078, 
( 


OK, visible, sound1, 
OK, visible, sound], 
OK, visible, soundi, 
OK, visible, sound! } 


Listing: MPWFinal.r 


/* This is the *Stick-it-all-together^ Rez file. */ 
/* file is part of the DMP-110 printer driver for the Mac 


* series of computers. */ 
INCLUDE “PACK”; 

INCLUDE "PDEFQ"; 

INCLUDE "PDEF4"; 

INCLUDE ^PDriver"; 

INCLUDE “dmp-118.rsrc’; 
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C Workshop 
Writing INITs in THINK C 


Writing INITs Using THINK C 
Introduction 

THINK Cprovides aconvenient and powerfulenvironment 
for creating INITs. INITS are code resources, stored in the 
System Folder, that are automatically run at startup. THINK C 
allows the programmer to easily access global variables from an 
INIT, as well as providing an inline assembler to deal with 
situations when C code alone may not be sufficient. This article 
will present a simple, but complete, INIT created with THINK C. 
In addition, the details of how THINK C handles code resources 
will be presented along with some general rules for writing 
INITs. While the examples presented here are written in THINK 
C, many of the techniques, tips, and discussions apply to writing 
INITs in any language. 

Building an INIT in THINK C is the same as building any 
other type of code resource such as CDEF, LDEF, WDEF, or 
FKEY. You use “Set Project Type...” to indicate that the project 
is a Code Resource, and you set the “File Type” field to INIT. To 
be safe, you should use the Attributes field to set the lock bit and 
reset the purge bit so that your INIT code won’t get moved or 
purged unexpectedly. Set the System Heap bit to ensue that the 
INIT is loaded into the System Heap, not the Application Heap. 
If you do not select the “Custom Headers” option THINK C 
installs some header code that loads AO with the address of your 
code resource and then branches to your “main” routine. For the 
purposes of this article, the default THINK C header will suffice. 

THINK C comes with a set of macros contained in the file 
“SetUpA4.h” which take care of the necessary details so that you 
can access global variables from within your INIT. THINK C 
maintains your global variables as part of the code resource that 
makes up the INIT, placing the global variables at the end of the 
code resource. Since THINK C generates code that accesses 
these variables with a word as an offset, the maximum combined 
length of the code and all global variables is 32K. The 
"SetUpA4.h" file generates a small portion of code, so it should 
only be included once. 


INIT Installation 

Most INITS consist of two main parts. The first is the 
installation code which is executed at start up time. This code 
usually patches afew traps and returns control to the system. The 
second portion of the INIT is the code that will be executed when 
the patched trap is called. Some INITS do not patch any traps but 
may instead install VBL tasks or load various drivers. 

The Main procedure in your THINK C project is the instal- 
lation code. It is called immediately after your INIT is loaded. 
Main must perform several tasks so that the trapped patches will 
function properly. The first task is to remember the address that 
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the INIT resource was loaded at so that global variables may be 
accessed. The following code fragment illustrates the essential 
elements. 


Sinclude «SetUpA4.h» 
Handle myINITHandle 
maint) 


Ptr myINITPtr; 


asm ( 
move.L A®,myINITPtr; 


Remember AQC); 

SetUpA4(); 

myINITHandle = RecoverHandleC myINITPtr ); 
DetachResource( myINITHandle); 


RestoreA4(); 
) 


The very first line of code in Main stores the contents of 
register AO in the local variable myINITPtr. This value must be 
stored in a local variable, as global variables are not yet available 
at this point in the code. Once this is done, the macros Remem- 
berA0 and SetUpA4 from the “SetUpA4.h” file are called. 
RememberAO causes the current value of AO to be stored away 
(in a memory location reserved in the code generated 
“SetUpA4.h”), and SetUpA4 causes A4 to be loaded with the 
address of our INIT code resource. THINK C generates global 
variable references relative to A4 for code resources, so global 
variables may be referenced after the call to SetUpA4. The next 
step is to use the address of the INIT code resource that we saved 
(which is a separate copy from the one saved by the call to 
RememberAO) to recover the handle to our code resource and 
save that away in the global variable myINITHandle. 

INITs are discussed in Inside Macintosh IV-256 which 
states that on entry to your INIT code the operating system “saves 
all registers and places the handle to your ‘INIT’ resource in 
register AO." This can lead to some confusion because the default 
THINK C header fora code resource places a pointer to your code 
resource in register AO. This destroys the handle to your INIT 
resource that the operating system put into AO, thus the call to 
RecoverHandle is required to get the handle of the INIT code 
resource. 

The next line performs a DetachResource on the INIT code. 
This is necessary so that your INIT will survive beyond system 
start up. When you return from your INIT to the operating 
system, the resource file of your INIT is closed causing the INIT 
code resource to be purged from memory. Calling DetachRe- 
source forces the Resource Manager to forget that it ever knew 
about the INIT resource, so it is not purged. 
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Following the DetachResource call is any installation code 
for the INIT. This is where trap patches (discussed below) are 
placed. Ending the installation procedure is a call to RestoreA4 
which simply restores the value to A4 that was present when 
SetUpA4 was called. RememberA0 should only be called once 
In your entire INIT, at the start of the installation procedure. 
SetUpA4 and RestoreA4 should always be called in pairs, in the 
same procedure. SetUpA4 stores the old value of A4 on the stack 
so that if you call RestoreA4 in a function other than the one that 
contained the SetUpA4 you will likely die a quick and violent 
death. 

If you did not set the Lock bit in the “Set Project Type...” 
dialog, you should lock the INIT with a call such as 

HLock(myINITHandle); 

after the RecoverHandle call in your Main procedure. If you 
don't make sure that your INIT is locked and unpurgeable, it 
could very well be unexpectedly moved or removed by the 
Memory Manager. 


Accessing the INIT File After Start Up 

As mentioned above, at start up time, after your INIT returns 
from its Main procedure back to the operating system, the INIT's 
resource files are closed. Unfortunately, often times your INIT 
may need to access its resource or data fork at some later time. As 
good Macintosh developers, we all want our users to be able to 
rename their INITs. So it now becomes necessary to hunt down 
the name of our INIT file during start up and store itaway to later 
to access the file. This can be accomplished with the following 
function which stores the name of the INIT file in the variable 
“пате” passed to it. The passed variable should probably be a 
global variable. 


f indMuName (name 2 
ү name; 


FCBPBRec p; 


p.ioCompletion = 0; 

p.ioRefNum = CurResF ile(C); 
p.ioVRefNum = Ø; 

/* next line is required, but why? */ 
p.ioNamePtr = (StringPtr пате; 
PBGetFCBInfoC&p, false); 


BlockMove(p.ioNamePtr, &name, 
1 + *(сһаг *)(p.ioNamePtr) ); 
) 


The above function should be called very early in your 
installation code as it relies on the fact the the current resource 
filesisthe INIT. This will not be the case if you have opened any 
other resource files. If you are going to the trouble of saving the 
name of your INIT file you might also consider saving the current 
volume reference number. Through System 6, all INITs are 
stored in the System folder. The volume reference number of the 
System folder is easily found using the SysEnvirons call de- 
scribed in IM V-5. It is possible in the future that Apple will 
create an “INIT Folder” or that a developer will release a product 
that allows users to keep INITs in a separate folder. Thus in self 
defense, it is probably a good idea to store the current volume 
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reference number at the same time you save the file name of your 
INIT if you plan to access your INIT file again. The current 
volume reference number can be found using the call GetVol as 
described In IM II-89. 

A secondary method of accessing resources in your INIT file 
is to load them into memory at start up time, and perform a 
DetachResource on each so they will not be purged. This 
solution is fine for a few small resources. However, memory will 
be unnecessarily tied up if you load many resources. Further- 
more, you have no way of permanently modifying resources if 
they are all loaded into memory. A reasonable approach would 
be to keep any small resources that you access regularly in 
memory all the time, and only access the INIT resource file for 
rarely used or very large resources. 

If you are loading resources at start up time that you intend 
to use at a later time, make sure that you set the System Heap bit 
on each one so that they are not loaded into the application heap. 
Furthermore, remember to call DetachResource on each re- 
source, or they will be purged when your INIT’s resource file is 
Closed by the operating system on return from installation. 


Patching Traps - Introduction 

Patching traps is a very powerful means of altering system 
behavior. While it is very powerful, it is also rather easy to make 
mistakes. A trap patch is installed by means of a call to 
NSetTrapAddress, usually after saving the old address of that 
trap by calling NGetTrapAddress. Traps are not usually com- 
pletely replaced by a patch. Instead, the data passed to the trap 
is intercepted before the actual trap gets to it, or by modifying the 
data after the trap is finished, but before it returns to the calling 
program. In effect, installing a patch trap puts another level of 
code between the calling program and the various operating 
system managers. Because trap patches may get called very often 
(for example a patch on GetNextEvent, common in most screen 
saver and macro packages) they should execute quickly, so as not 
to slow the system down. 

There is no simple formula for writing a function to behave 
asatrap patch. You must read the Inside Macintosh description 
of the trap you wish to patch with great care. There are two 
different kinds of traps, Operating System and Toolbox. Oper- 
aung System calls pass their parameters in registers. Thus for 
Operating System traps, itis necessary to include some assembly 
language code. Toolbox traps use Pascal calling conventions, so 
they pass their parameters on the stack. THINK C can mimic 
Pascal calling conventions, so in most cases no assembly lan- 
guage is needed to patch Toolbox traps. 

I know of no definitive way to tell a Toolbox trap from an 
Operaung System trap except to look at its Inside Macintosh 
definition and see if it gives register usage. If there is no register 
description it is probably a Toolbox trap. Of course there are 
several parts Operating System traps that do not provide register 
information with the description. As an example, the new HFS 
calls were implemented through a single trap called HFSDis- 
patch. A routine selector value is placed in register DO to tell the 
operating system which routine is desired. The List Manager is 
asomewhatdifferent example. All List Managercalls go through 
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one trap, “Pack0”. A routine selector value is passed as a word 
on the stack to indicate which routine to actually call. However, 
the vast majority of calls are fairly straightforward to handle. 


Patching a Toolbox Trap 

Asan example, we willnow see how to patch BeginUpdate. 
This is trap A922, and is part of the Window Manager. Before 
going into the details of the trap patch code itself, it is necessary 
to actually install the patch. As mentioned above this is done with 
NGetTrapAddress and NSetTrapAddress. These are newer 
version of SetTrapAddress and GetTrapAddress, and should 
always be used as they allow you to specify whether the trap 
being patched is an Operating System or a Toolbox trap. The 
following code fragment, combined with the outline of Main 
above, shows how to install patch on BeginUpdate. 


Sdefine BeginUpdateTrap 0хА922 
long oldBeginUpdate; 
main() 


/* start code */ 


oldBeginUpdate = NGetTrapAddress 
(BeginUpdateTrep, ToolTrap); 

NSetTrapAddress (newBeginUpdate, 
BeginUpdateTrap, Тоо1Тгар); 


/* end code */ 


) 


The address of the original trap for BeginUpdate is stored in 
the global variable oldBeginUpdate, so that we can call the 
original routine from within the patch. Next, the address of the 
patch function, newBeginUpdate, is installed as the new address 
for BeginUpdate. The trap number of BeginUpdate is #defined 
to 0xA922 and used in the two calls. Some developers pass 
0x0922, dropping the A. Inside Macintosh is not explicit about 
this matter, simply saying to pass the "trap number." However, 
in Apple'sownINIT code, they usually pass the trap number with 
the preceding A. 

The calling definition of BeginUpdate, as given in IM I-292, 
is: 

BeginUpdateCwind: WindowPtr); 

An equivalent function prototype for THINK C, to be 

included in the header of your program, would look like: 


pascal void newBeginUpdate(WindowPtr w); | 
The function to patch BeginUpdate would have an outline as 


follows: 


pascal void newBeginUpdate(w) 
WindowPtr w; 


бе ШрА4С); 

/* pre-processing goes here */ 

CallPascal(w, OldBeginUpdate); 

/* post-processing goes here */ 
RestoreA4C); 


) 


By using the prefix "pascal" we are telling THINK C to use 
Pascal calling conventions for this procedure. By giving the 
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function the exact same definition as the trap we are patching, we 
can easily access its parameters. In fact the variable w is the 
WindowPtr for window that is to be updated. Thus we can access 
the entire window structure and make any necessary modifica- 
tions. The calls to SetUpA4 and RestoreA4 should begin and end 
the trap patch so that all global variables will be available 
throughout the patch. 

THINK C provides the CallPascal function so that we can 
call Pascal style routines without reverting to assembly language. 
The CallPascal functions are described in detail in the THINK C 
User’s Manual on pages 119-120. If the function that you are 
calling returns a value, other versions of the CallPascal function 
should be used, as described in the THINK C manual. In this use 
of CallPascal we are calling the original BeginUpdate routine 
that existed before we patched the BeginUpdate trap, so we 
simply pass the Window Pointer w and the address of the routine 
to CallPascal, and THINK C takes care of the details. 


Patching An Operating System Trap 
With a few exceptions, operating system traps do not store 
any parameters on the stack, rather they pass them in registers. 
Thus operating system trap patches must be handled differently 
than toolbox traps. Declare the function that will serve as the 
patch with no return value and no parameters in the header of the 
program, such as: 


void osTrapPatch(void); | 
The beginning of the function then includes some assembly 


code to save the contents of the parameter registers. Calling the 
original trap must be done with assembly code as well, first 
restoring the appropriate parameters into the registers, and then 
calling the original trap. Furthermore, some operating system 
traps return values in a register (commonly DO). This value must 
be saved on return from calling the original trap, and placed in the 
appropriate register immediately before returning from the 
patch. 

SetFileInfo ( trap AOOD, IM II-116) takes a parameter block 
pointer in register AO and returns an error code as a word in 
register DO. The following example code assumes that the trap 
patch has been installed using the same procedure as shown 
above for BeginUpdate. 


Sdefine SetFileInfoTrap @xA00D 
void newSetFileInfoCvoid); 
long oldSetFileInfo; 


void newSetF ileInfo(C) 


HFileParam *PBPtr; 
int saveD0; 
/* save original parameter block pointer */ 
asm ( 
move.L AQ,PBPtr 


/* make global variables available */ 
SetUpA4O; 
/* do any pre-processing */ 
asm ( 
/* set up the parameter block pointer */ 
move.L PBPtr, Ad 
/* get address of original trap */ 
move .L oldSetFileInfo,A1 
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/* call original trap */ 

jer CAI) 

/* save return value, error code */ 
move .W 00 5әуе00 


/* do any post-processing */ 
/* restore original value of A4 */ 
RestoreA4(); 
/* set-up return value */ 
asm ( 
ле saveD0,D0 


Coping with the Trap Dispatcher 

When any trap is called, the Trap Dispatcher is invoked first. 
The Trap Dispatcher performs some general house keeping 
before calling the actual routine. One task it performs that can 
cause problems, is the storing of the actual trap number that was 
called in register D1. Apple has never documented this fact, so 
it may very well change. In self defense you may want to use 
some assembly language to save the value of D1 on entry to your 
patch, and restore its value immediately before calling the 
original trap. In fact, if you want to be very safe, you may want 
to save and restore other registers as well. The outline of the code 
for saving and restoring D1 follows. 


[s patch() 
long saveD 1; 


asm { 
move.L D1,saveD 1 


SetUpA4C); 
/* any pre-processing */ 
asm ( 

move.L saveD1,D1 


/* call the original trap */ 
/* any post-processing */ 
RestoreA4(); 


) 


Note that saveD1 is a local variable because calling Set- 
UpA4 could destroy the contents of D1. Before SetUpA4 is 
called only local variables are accessible. It is not necessary to 
restore the value of D1 before returning from the patch, although 
as a defensive measure you may want to. 


Memory 

When writing a trap patch you should check IM to see if the 
trap you are patching could move memory. Ifitcan, then you can 
make all the Memory Manager calls you like. If the trap you are 
patching does not move memory according to IM then you better 
avoid calling the Memory Manager or any operating systems 
routines that could call the Memory Manager. If you move 
memory on an application when it isn’t expecting it, you will 
have created a worthless INIT. 

If you intend to allocate memory, it is important that you 
consider whether you need to allocate memory in the system heap 
or the application heap. Any memory that is allocated in an 
application’s heap will be lost when that application quits, 
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whereas system memory will remain until the machine is reset. 
During start up, if you allocate memory it may end up going into 
a temporary application heap that is set up for INITs. This is fine 
for temporary work, but not if you need to allocate a block of 
memory for later use. There has always been a way to allocate 
memory in the system heap, but it requires the use of assembly 
language. With THINK C you can create a few simple proce- 
dures for allocating memory in the System heap. Apple describes 
these in Tech Note 4219, "New Memory Manager Glue Rou- 
tines," and their definitions are given below. Note that once the 
handle or pointer is allocated in the system heap, standard 
Memory Manager calls can be used to manipulate them. Further 
discussion of this can be found on page 151 of the THINK C 
User's Manual and IM II-32, 36. 


Handle NewHandleSys( length) 
long length; 
( 


asm ( 
move.L length,D0 
NewHandle SYS 
ын А02 ,00 


) 


Ptr NewPtrSus(length) 
long length; 
( 


asm ( 
move.L length,D0 
NewPtr SYS 
dina A0, DØ 


) 


Calls such as NewHandleSys and NewPtrSys are used for 
grabbing ablock of memory. However, they donot guarantee the 
memory will actually be available at start up time. In Inside 
Macintosh IV, a tricky method of expanding the System Heap is 
described. Fortunately, in Volume V a simpler solution is 
presented although its description is less than detailed. Simply 
include a “sysz” resource with ID=0 in your INIT file. This 
resource consists of a single long word that specifies the number 
of bytes of memory your INIT needs. The operating system will 
attempt to grow the system heap by that amount before loading 
your INIT. If your INIT does not contain a “sysz” resource, the 
system heap is expanded by 16K. When you return from your 
INIT’s installation code, the system heap is compacted so that 
any memory that you didn’t explicitly allocate is lost. All the 
"sysz" mechanism does is to make sure that a certain amount of 
memory is available for allocation. It does not actually allocate 
or reserve the memory for your INIT. 


Warning 
Tech Note #212, “The Joys of Being 32-Bit Clean,” states 
"Make sure that any patch you do write is not a tail patch... You 
need to avoid tail patches because many of Apple's System 
Software patches check the return address on the stack to see who 
called them. If you write a tail patch, you defeat these checks and 
may cause things to break in strange and less than wonderful 
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ways.” Unfortunately, any trap patch written using the C func- 
tion technique described here are effectively tail patches. 
However, I have yet to find a case where this actually causes a 
problem. Furthermore, in many cases it is impossible to obtain 
the desired result without writing a tail patch. It seems unlikely 
that Apple will declare war on tail patches in future Systems, as 
there are already tons of tail patches out there. However, it is 
possible that this could cause problems in some rare instances. 
Unfortunately, the alternative is to write lots more assembly 
code, and that isn’t a terribly appealing option. 


Communicating with the User at Start Up 

At installation time, many INITs may want to do something 
beyond simply installing a trap patch. In some cases, the INIT 
may need to interact with the user through a dialog. Apple is 
silent on this issue, although their own AppleShare INIT puts up 
an interactive dialog at start up. After some experimenting and 
disassembly I have come up with a way to handle dialogs at start 
up. The approach is very similar to what you do in a normal 
application. You must initialize various managers. The problem 
is that you should not initialize every manager, and there are 
some other matters to be taken care of. The sequence of calls 
below will set up the system so that the Dialog Manager may be 
used. 


InitFontsC2: 
Ini tWindowsO; 


TEInitO; 
InitDialogsC21); | | 
There are still a few of catches though. QuickDraw requires 


that A5pointto a setof its global variables. Asan INIT,we don't 
automatically get our own set of QuickDraw globals. Fortu- 
nately, the operating system provides us with a set we can use. 
All you have to do is load A5 from the global variable CurrentAS. 
This should be done before initializing any of the managers. The 
following line of assembly does the job. 


asm { 
move .L CurrentA5, А5 


These is no need to restore А5 to its original value as the 
operating system saves all registers before calling your INIT, and 
restores them on return. 

One unfortunate side effect of calling InitWindows is that 
the entire screen 1s redrawn, so any icons drawn by INITs loaded 
before yours are lost. If you only want to draw an INIT at start 
up to notify the user that your INIT has been installed, get a copy 
of Paul Mercer's ShowINIT code (which is available as a THINK 
C project) and use it. Almost everyone who puts up an icon at 
start up uses Mercer’s code or a variant of it. ShowINIT makes 
sure icons don’t overlap and so on. A really useful piece of code. 

There are two low memory globals that have not been 
initialized at the time INITS are loaded which can cause prob- 
lems. These are DeskHook and DragHook which are both set to 
-] when INITs are loaded. If the operating system tries to branch 
through these vectors, an address error is generated and the 
system error handler steps in. Simply setting these two globals 
to zero before initializing any of the managers solves the prob- 
lem. 
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DeskHook = 91; 
DragHook = 91; 

It is possible, although highly unlikely (since these globals 
are no longer used under MultiFinder) , that a previous INIT or 
the operating system could have put a value into DeskHook and/ 
or DragHook. For this reason, a more defensive method of 
handling these two globals is to test each to see if they contain an 
odd number. If so, set them to zero; otherwise assume that they 
are valid and leave them alone. 


Uninstalling a Trap Patch 

In most cases, once you have installed a trap patch you will 
not want to uninstall that trap patch. In some cases however, you 
may wantto disable or remove the patch. Unfortunately, another 
INIT or application may have installed a patch on top of your trap 
patch. They have probably stored yourentry address so thatit can 
be called directly. Furthermore, some applications store the 
address of certain traps and call them directly to avoid the 
overhead of the Trap Dispatcher on each call. If you change the 
address of a trap after any other INIT or application has had the 
opportunity to execute, there is a chance that the system will be 
corrupted. In fact some INITS that users have found must load 
last make this mistake. The solution is not to change the trap 
address again, but to store a global state variable that indicates 
whether or not the INIT is active. The global variable can then 
be checked in each patch, and if the INIT is inactive, you can 
simply call the original trap without further intervention. There 
are more sophisticated ways to uninstall a patch which can even 
release most of the memory claimed by the INIT code, but they 
involve assembly language and/or self modifying code. 


An Example 

To illustrate some of the points made in this article, the 
following sample INIT has been provided. The INIT is a simple 
virus protection program. It intercepts two resource manager 
traps, ChangedResource and AddResource. Many viruses de- 
pend on these two calls to work. This INIT is not intended to be 
a full fledged virus protection program, but rather an example of 
how an INIT works. A listof resource types to watch is contained 
in the *ResT' 256 resource. Initially this only contains CODE, 
INIT, and nVIR resources. This may be modified with ResEdit 
as desired. If the INIT detects a ChangedResource or AddRe- 
source call involving any resource type listed in the 'ResT' 
resource, it puts up a dialog warning the user about the pending 
action. The resource type, id number, name, and file name are 
displayed. The user may select OK to allow the operation to 
continue or Cancel to stop it. [This example is NOT meant for full 
virus protection; so don't use it as such. This is an EXAMPLE 
on how to write an INIT; use it that was.-ed] 

If the user holds down the mouse button when the INIT is 
loaded, it will not install itself. This feature can be useful when 
debugging the INIT and in cases where the user doesn't want to 
load an INIT for a particular session. Many INITs currently use 
this approach. It would be easier for users if all INITs adopted 
such an approach. 

The sample INIT illustrates the basic techniques described 
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here, but does not get into some of the more complex techniques 
in the interest of brevity and clarity. The INIT should be 
compiled with the “Precompiled Headers” option on. 


Listing: example.c 
*Sinclude «SetUpA4.h» 
def ine ni! 21 


def ine ChangedResourceTrap @xA9AA 
8def ine AddResourceTrap 0xA9AB 


Handle queryDITL; /* DITL for unknown dialog */ 

Handle resourceTypes; /* handle of rsrc types to watch */ 
long oldChangedResource; /* addr of original ChangedResource*/ 
long oldAddResource;  /* address of original AddResource */ 
5іг255 trash; /* needed due to Apple bug ? */ 


pascal void NewChangedResource(Handle h); 

pascal void NewAddResource(Handle h, ResType rType, int id, 
Str255 name); 

Boolean userDialog(); 

Boolean inList(ResType type, Handle list); 

Str255 *findFileNameCint refNum); 

void main(void); 


pascal void NewChangedResource(h) 
oe h; 


int id; 

ResType type; 

Str255 resName, num; 
Boolean ok; 


SetUpA4(); 


ok = true; 
GetResInfoCh, kid, &type, &resName); 


if CinListCtype, resourceTypes) ) 
ok = userDialog(*\pAttempt to Change Resource’, 
type, id, &resName, HomeResFileCh) ); 


1f Cok) 

CallPascal(h, oldChangedResource); 
else 

ResErr = resAttrErr; 


RestoreA4(); 


pascal void NewAddResource(h, rType, id, name) 
Handle h; 
ResType rType; 
int id; 
oo name; 

Boolean ok; 

SetUpA4(); 

ok = true; 

if CinList(rType, resourceTypes) ) 

ok = userDialog(”\pAttempt to Add Resource", 
гТуре, id, name, CurResFile() ); 
1f Cok) 


CallPascal(h, гТуре, id, name, oldAddResource); 


else 
ResErr = addResFailed; 
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RestoreA4C); 


Boolean userDialog(message, type, id, resName, file) 


Str255 *message; 
ResType type; 
int id; 

Str255 *resName; 
int file; 


GrafPtr oldPort; 
Handle tempH; 
DialogPtr d; 

int i; 

Rect r; 

Str255 num; 


GetPortC&oldPort); 
tempH = queryDITL; 


HandToHand(&tempH ) ; 
SetRect(&r, 90, 68, 444, 226); 


d = NewDialog(nil, &r, nil, true, 1, -1, false, nil, tempH); 


SetPort(d); 

МоуеТ0(20,20); 
DrawString(message); 
Movelo(20,40); 
DrawString(*\pResource Type: ”); 
DrawText(&type, 0, 4); 
Movelo(20,60); 
DrawString(”\pResource ID: ^); 
NumToString(Clong)id, num); 
DrawStringCnum); 

MoveTo( 28,88); 
DrawString(”\pResource Name: ^); 
DrawString(resName); 

МоуеТ0(20, 100); 
DrawString(“VpFile Name: ”); 
DrawString( findFileNameC file ) ); 


do ( 
ModalDialog(nil, &i); 
) while C i != 1&& í !=2 ), 


DisposDialog(d); 
SetPortColdPort); 


return( i == 1); 


Boolean inList(type, list) 
ResType type; 

Handle list; 

( 


int len; 
ResType *resPtr; 


len = GetHandleSize(list) >> 2; 
resPtr = (ResType *)*list; 
while ( len- ) 
if (*resPtr** == type) 
return( true); 
return(false); 


5іг255 *findFileNameCrefNum) 
int refNum; 
FCBPBRec p; 


p.ioCompletion = 0; 
p. ioRefNum = refNum; 
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p.ioFCBIndx = 
p.ioVRefNum = 
p.ioNamePtr = (StringPtr)trash; RestoreA4(); 
PBGetFCBInfoC&p, false); ) 


0; NSet TrapAddress(NewAddResource, AddResourceTrap, Тоо1Тгар); 
0, 


return((Str255 *)bp.ioNamePtr); Listing: Exaaple.r 
) resource ‘DITL’ (256, sysheap) ( 
( /* (1) */ 
/*This block is called once. It saves the pointer (129, 270, 149, 330), 
to this code resource, and installs the patch. */ Button ( 
void maint) enabled, 
( “оқ” 
Handle muHandle; ), 
Ptr myPtr; /* [2] */ 
SysEnvRec world; (129, 189, 149, 249), 
Str255 *namePtr; Button ( 
enabled, 
esn ( "Cancel" 
move.1 Ай, myPtr ) 
RememberA0(); ); 
SetUpAÀA4(); 
ifCiButtonO ( resource ‘sysz’ (0) ( 
myHandle = RecoverHandle(muPtr); 0x0800 
DetachResource(muHandle); E 
resourceTupes = GetResource(‘ResT’, 256); resource 'ResT^ (256, susheap) ( 
DetachResource(resourceTupes); ( /* (1) */ 
VIR’, 
queryDITL = GetResourceC'DITL^, 256); /* (2) */ 
DetachResource(queryDITL); ‘INIT’, 
/* [3] */ 
oldChangedResource = ‘CODE’ 
NGetTrapAddress(ChangedResourceTrap, ToolTrap); ) 


NSetTrepAddressCNewChangedResource, ChangedResource Trap, ToolTrap?; 


oldAddResource = 22) 
NGetTrapAddress(AddResourceTrap,ToolTrap); | 
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Introduction 

The MIDI Manager is Apple’s new standard MIDI tool set. 
It enables developers to cleanly transfer MIDI data to and from 
synthesizers and other concurrently running applications. It 
supplies a complete MIDI tool set which is as powerful as any 
existing implementation, yet strictly adheres to system guide- 
lines. Included with the MIDI Manager are the Apple MIDI 
Driver and PatchBay. 

The Apple MIDI Driver interprets all incoming and out 
going MIDI messages and handles all serial port I/O. This 
includes various modes of time code generation and concurrent 
asynchronous serial port communication. PatchBay is Apple’s 
graphical user interface for the MIDI Manager. Supplied as a 
utility application and a Desk Accessory, PatchBay enables users 
to intuitively route MIDI data and time code to and from the 
Apple MIDI Driver as well as throughout multiple applications 
running under Multifinder. The MIDI Manager proper, how- 
ever, supplies all internal communications and supplies a thor- 
ough and very powerful MIDI tool set. 


Main Concepts 

From the music software developer's pointof view, the main 
components of the MIDI Manager are clients and ports. A client 
is any program that uses the MIDI Manager's facilities. Al- 
though an application usually needs only one client, it can 
actually have several. Each client can, and usually does, create 
multiple ports which are basically unidirectional streams of 
MIDI information. Each port can be either a time port, which 
provides the MIDI Manager's timing facilities, or a data port, 
which is used to read or write MIDI packets. The data ports are 
further divided into input and output ports. A client's ports can 
be connected to one of its own ports or to any other client's ports; 
however, input ports can only be connected to output ports (and 
vice versa). Time ports enable port synchronization: when a time 
port's clock ticks, all clocks of all ports connected to it tick 
synchronously. Data ports send and receive MIDI data such as 
note-on/note-off or system exclusive messages. Input and output 
ports respectively receive and send MIDI data to the ports of 
MIDI drivers or other MIDI Manager compatible applications 
running concurrently under Multifinder. We will now illustrate 
the proper use of the MIDI Manager through the explanation of 
a sample application called MIDIArp. 


The MIDIArp Demo Application 
MIDIArp is a simple arpeggiator program [tone generator 
for those who are not blessed with a huge vocabulary like Don's. 
-ed] that illustrates the use of the MIDI Manager's data and 
timing facilities. MIDIArp simply reads in note-on data and 
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arpeggiates it until corresponding note-off data is received. The 
basic flow of MIDIArp is quite simple: after MIDIArp initializes 
the various Macintosh Managers, it signs into the MIDI Man- 
ager, callsaroutine to set up its time, input, and output ports, pops 
up its main dialog box, and cycles through its main event loop. 
The main event loop simply checks for user (console) input, and 
adjusts its arpeggio direction and speed parameters accordingly. 
Once the quit button is selected, MIDIArp signs out from the 
MIDI Manager and terminates. During the main event loop, 
however, MIDIArp continually arpeggiates its MIDI input at 
interrupt level via its readHook and timeProc routines. 


MIDIArp.h 

MIDIArpincludesa header file, MIDIArp.h, which contains 
its main data structures and symbolic constants. In addition to the 
standard user interface constants for menu and dialog resource 
ID's, constants are defined to identify our own resource of type 
‘port’. We define three such ‘port’ resources: one for each 
MIDI Manager port we intend to use. This is necessary in order 
to save the state of our patch between each launch of the 
application. For readability, several MIDIArp constants are 
defined followed by several constants local to the MIDI Manager 
itself. Specifically, we define our client and ‘ICN#’ resource ID, 
both of which are used to sign in to the MIDI Manager. The client 
ID is a four-byte OSType (and by convention, although not by 
necessity, our client ID is used as our application signature). 
We then define our port ID’s which are also of type OSType. The 
actual ports will be displayed by PatchBay from top to bottom 
in ascending alphabetical order. (It is recommended that time 
ports be displayed above the data ports that are synchronized to 
them, and that an application’s input and output ports be dis- 
played in the reverse order of that used by the Apple MIDI 
Driver.) 


After several MIDI Manager parameters are symbolically 
defined, we define our main data structures. The first data 
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structure that we will need is a Notelnfo record which contains 
fields to store the MIDI channel, key number, and key velocity 
of each incoming note-on message. The NotelInfo record is itself 
an individual field of the main MIDIArp data structure ArpPar- 
ams. The ArpParams structure contains various fields of 
information concerning the current state of the MIDIArp client. 
In particular, it contains a field called Locked, which is used to 
prevent the structure from being modified while it is in use. 
Incoming MIDI data (notes that MIDIArp is currently arpeg- 
giating) are stored in an array of NotelInfo records called NoteTbl. 
Other fields hold information about things such as tempo and 
current arpeggiation pattern (e.g., whether we are currently going 
up or down, etc.). NextNoteOn isa field used to keep track of the 
exact time the next note is to be played. Finally, the ArpParams 
structure allows the storage of each port's reference number. 


MIDIArp.c 

The main source file for MIDIArp is MIDIArp.c. Here we 
first define several global variables, including an ArpParams 
recordcalled ArpGlobals,a variable to hold our current arpeggia- 
tion speed ID, anda flag (GManualPatch) to indicate whether the 
current port configuration (patch) has been set up by a (previ- 
ously saved) PatchBay patch or needs to be reconfigured by 
MIDIArp itself (based on its last configuration). The main() 
routine of MIDIArp calls InitThings() to initialize the Macintosh 
Managers, Arplnit() which signs-in to the MIDI Manager and 
sets up our ports, StartDialog() to bring up the main dialog box 
with default settings, and then RunDialog() to handle events. 
When the Quit button is finally hit, ArpClose() is called to sign- 
out from the MIDI Manager, and the main dialog box is shut 
down through a call to StopDialog(). InitThings(), in addition to 
initializing the various managers of the Macintosh, sets up a 
standard menu bar and seeds the random number generator for 
random arpeggiation. Arplnit(), on the other hand, completely 
sets up MIDIArp's MIDI Manager environment. In order to use 
the MIDI Manager we must first make sure that it is currently 
installed. This is achieved through a call to SndDisp Version() 
(sound dispatch version). Given the constant midiToolNum, 
SndDisp Version() returns the version of the currently installed 
MIDI Manager or zero if the MIDI Manager is not installed. 
Once we have concluded that the MIDI Manager is installed, we 
must sign in to the MIDI Manager (before we make any other 
calls) by calling MIDISignIn(). We pass as arguments to 
MIDISignIn() our client ID, our client reference constant, a 
handle to our “ІСМЯ” resource, and our client name string. The 
client ID is used for future MIDI Manager calls and allows other 
clients, such as patchers, to get information about us. The client 
reference constant, or refCon, is a general purpose parameter 
that is only really needed by certain types of applications (such 
as device drivers). The handle to the ‘ICN#’ resource and the 
client name string are passed to allow PatchBay (or any other 
clients) to display them via MIDIGetClientIcon() and MIDI- 
GetClientName(), respectively. 

The next thing we do in Arplnit() is add our time, input, and 
output ports via MIDIAddPort() and connect them accordingly. 
The tricky part is determining whether the ports will automati- 
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cally be connected via a saved PatchBay patch, or whether we 
must connect them ourselves. Therefore, we set the global flag 
GManualPatch to true before we add any ports allowing us to 
determine by the return value of MIDIAddPort() whether or not 
we need to connect the ports ourselves. If MIDIAddPort() 
returns midiV ConnectMade (virtual connection resolved), then 
we know that the ports were virtually connected by someone else 
viaMIDIConnectTime() or MIDIConnectData(. In this case 
we simply set GManualPatch to false indicating that we do not 
have to manually patch together the ports. If GManualPatch is 
still true after all ports have been added, then we will call 
PatchPorts() to do our own patching. 

The first port we add in Arplnit() is our time port or time 
base. We do this by calling MIDIAddPort(). This call will 
create a new port with attributes as described in an InitParams 
data structure; therefore, we must first set one up. The init record 
contains various information including items such as the port ID, 
the port type (time, input, output, invisible time) the port's 
readHook, the time format, port name, etc., and a port reference 
constant (refCon). If the port’s readHook routine is to be called 
at interrupt level, then the refCon can be used to store the 
contents of the application's AS register for global variable 
access. The same basic strategy is used for creating the input and 
output ports; however, MIDIArp by default wants its data ports 
to be sync' d to its time port. So before we actually add the port, 
we set the timeBase field of the InitParams record to our time 
port'sreference number (previously obtained when we added our 
time port). 

Now that all the ports have been added, we check GManu- 
alPatch, and, if it's still true, we call PatchPorts() to patch the 
ports as they were when we last quit. To reconfigure our port 
connections, we must read in the *port? resource of each port. 
The port resource is nothing more than the saved result of 
MIDIGetPortInfo() from our last session. 
MIDIGetPortInfo() returns a handle to a record containing the 
port type, time base of the port, and a list of all its connections. 

To reconfigure our time port, we first check its port info 
record (of its ‘port’ resource) to see if we should be sync'd to 
another client's time base. If so, we call MIDIConnectTimeQ, 
connecting the external time port to our time port (slaving us to 
it). If the result of MIDIConnectTime( is midiVConnectErr, 
then the external port’s owner is not currently signed in; other- 
wise, we must set our sync mode to externalSync. Next, we 
check to see if we are supposed to be the time base of one or more 
external ports. If so, we connect our time port to each. 

It’s a little less complicated to reconfigure our input and 
output ports. All we have to do is connect our input and output 
port to each of the ports listed in the PortInfo record contained in 
the corresponding ‘port’ resource. The last thing we need to do 
іп ArpInit() is start our time port's clock by calling MIDIS- 
tartTime(). Now that everything is set up, we simply cycle 
through our main event loop, waiting for the MIDI Manager to 
call our readHook routine with incoming MIDI data. 

In addition to handling user events, the main event loop 
periodically checks to see if an external time base has suddenly 
been connected to us. This is achieved by first detecting that 
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“something in MIDI Manager world has changed,” and then by 
checking our time port's info record to see if the MIDI Manager 
reports that we currently have an external time base. This 
situation arises if another client attempts to connect themselves 
to us or if a user of a patcher program (such as Patchbay) 
manually connects an external time port to ours. We check for 
either event in our main event loop by calling MIDI- 
WorldChanged(). If MIDIWorldChanged() returns true, 
then we know that something in the current world has changed; 
however, this could be caused by a client signing in or out, a port 
being added or removed, or aconnection being made or removed. 
Therefore, we must call MIDIGetPortInfo() on our time port 
and check whether the returned port information record reports 
that we currently have an external time base. If so, we then set 
our time port to external sync via MIDISetSync(); otherwise, we 
set it back to midiInternalSync (in the case that we were 
currently in external sync mode). The only thing left now is to get 
and process incoming MIDI data; this operation is handled at 
interrupt level through use of a readHook and a timeProc 
routine. 

Before jumping into the details, a general explanation of the 
interrupt level control flow of MIDIArp’s readHook and time- 
Proc is needed. The readHook is called by the MIDI Manager 
whenever an incoming message becomes “current.” When the 
first note of an input sequence is sent to MIDIArp’s input port, the 
MIDI Manager calls MIDIArp’s readHook which then copies it 
into the application’s note table buffer and calls the timeProc to 
take care of the output. When called, the timeProc determines 
the next note in the note table to be played, writes out the selected 
note, and then tells the MIDI Manager exactly when to call the 
timeProc for the next output. In other words, the only time the 
MIDIArp application calls its timeProc is from within its read- 
Hook, and this is done only when it receives the first note of an 
input sequence. After that, the timeProc itself is responsible for 
setting up its next wake-up. 

As summarized above, MIDIArp's readHook ArpReader() 
reads all incoming data, and starts a series of timeProc wake-ups 
which create the arpeggiation effect. As you may recall, the 
refCon field of the initialization record of each port was set to 
point to our application's global variables and passed as an 
argument to MIDIAddPort() when the port was originally 
created; additionally, the readHook field of the input port's 
initialization record was set to the address of ArpReader(). When 
the MIDI Manager calls a port's readHook, it passes two 
parameters: the next "current" MIDIPacket, and the port's 
refCon value. Because the MIDI Manager calls ArpReader() at 
interrupt level, the readHook first sets up our A5 world. This is 
achieved by calling the System routine SetA 5() with the refCon 
parameter. Since we will be modifying the note table in the 
ArpGlobals record, we must check whether any other routine is 
currently reading it by checking the Locked field. If it is locked, 
we simply return midiKeepPacket, which tells the MIDI Man- 
ager to save the new packet — we'll get it later. The packet is of 
interest to MIDIArponly if itis does notcontaina MIDI Manager 
System specific message (indicated in the message type field of 
the flags byte), and does contain a note-on message. If these 
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conditions are satisfied, then we set the return value to midi- 
MorePacket, telling the MIDI Manager that we now have this 
packet and that we want the next one. 

Before we actually return, however, we process the current 
packet. If the status byte in the packet indicates a note-on 
message, then we copy it into our note table and increment our 
current note count. If our note count is now equal to 1 (i.e., this 
is the first note of an arpeggio), then we call ArpTimeProc() to 
initiate an arpeggiation. (ArpTimeProc() is the routine that 
actually writes out the MIDI data.) If the status byte in the packet 
is a note-off message, however, we locate the matching note in 
the note table; and, if it’s still a valid note (it didn’t get "stolen"), 
then we simply delete it from the note table and decrement the 
table's current note count NumNotes. (A note can get "stolen" if 
there are 32 notes in our note table and a new note that is lower 
than the highest note is inserted.) Finally, we restore the system's 
A5 world and return. 

As mentioned above, we call our timeProc ArpTimeProc() 
from our readHook ArpReader() when we get the first note of an 
arpeggiation series. However, it is quite common for the MIDI 
Manager to call a timeProc at interrupt level (per an application 
scheduled event that will be illustrated below). This can be set 
up by calling the MIDI Manager routine MIDIWakeUp() with 
several arguments which include the reference number of a 
specific time port, a time, a period, and a pointer to the timeProc. 
In this case, the MIDI Manager calls the timeProc with the time 
port's current time and refCon. 

When our readHook ArpReader() calls our timeProc Arp- 
TimeProc(), however, it passes it the time stamp of the current 
MIDI packet (which in this case is not used) and the refCon 
parameter that was passed to ArpReader(). (The refCon of each 
port points to MIDIArp's global variables.) Once in control, the 
timeProc again sets up MIDIArp's A5 world via its refCon 
parameter (because it may be called by the MIDI Manageras well 
as from within the readHook). We then lock the ArpGlobals 
Structure so that ArpReader() won't disturb it. If at this time there 
are no notes in our note table, then we simply cancel any pending 
wake-ups and return. Otherwise, we bump the note table index 
tothe next note to be played. However, we must avoid the special 
case where the first note of an arpeggio may unintentionally be 
played twice in a row. (For example, the arpeggiation pattern is 
"Up," two notes are struck “at same time," and the first note 
received is higher than the second note. The first note received 
gets index 0, noteTbleIndex is set to 0, and the note is played. 
When the next note is received, the previous note is moved to 
index 1, the new note is inserted into index 0, and the noteTblIn- 
dex is bumped to index 1, which is the note that gets played. This 
means that the first note will be perceived to be played twice!) To 
avoid this sequence of events, if the note that we played the last 
ume the ArpTimeProc() was called (LastNote) is the same note 
as our new one, then we bump the note index once more. Now 
we can finally write out a note-on message by calling 
MIDIWritePacket(). And, because we know the duration of the 
note, we we can write out its corresponding note-off by simply 
adjusting the time stamp and calling MIDIWritePacket() again 
with the same packet. The MIDI Manager will make sure that the 
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packet is actually written out at the specified time. 

The last thing we do in ArpTimeProc() is schedule the time 
that the MIDI Manager should call ArpTimeProc() to write out 
the next note (this is what creates the io effect). We first 
set NextNoteOnTime to itself plus the value of Tempo; however, 
we want the ArpTimeProc() to be called (and write out the 
packet) soon enough before NextNoteOnTime such that the next 
call to MIDIWritePacket() will be before the packet’s time 
stamp expires. Although we call MIDIWritePacket() with an 
accurately time-stamped packet, we call it early to avoid the 
chance of the note being received late due to processing time. 
The basic rule of thumb is to always write early, making sure that 
. the time stamp (which is some time in the future) is accurate. 
Finally, we unlock the ArpGlobals structure, restore the system’s 
AS world, and return. 

And that’s it! The readHook continues reading incoming 
MIDI data, and the timeProc continues scheduling it to be 
written out. This continues until the user hits the Quit button. 
When this happens, we call ArpClose() to save our current patch 
configuration into the applications ‘port’ resource and sign-out 
from the MIDI Manager. 


How to Put It All Together 

Before running MIDIArp, however, the MIDI Manager 
must be installed. Installation consists of nothing more than 
moving the MIDI Manager and Apple MIDI Driver files into the 
System folder and restarting the Macintosh. Once the MIDI 
Manager is installed, PatchBay andany other MIDI Applications 
can be launched. 

Under single Finder, use the PatchBay DA to connect a 
single application to and from the Apple MIDI Driver; under 
MultiFinder however, use the PatchBay application. Once 
PatchBay and one or more MIDI-Manager-compatible applica- 
tions or drivers are up and running, the input, output, and time 
ports of the applications or drivers can be connected to them- 
selves, other applications, and to the Apple MIDI Driver in any 
proper configuration. 

When a MIDI instrument is connected to the Macintosh and 
MIDIArp is launched, the mouse can be used used to connect 
MIDIArp's output port to the Apple MIDI Driver's input port, 
and to connect the MIDI Driver's output port to MIDIArp's input 
port. (The MIDI Driver's input port can be thought of as the 
Macintosh's output port and visa versa). In this configuration, 
MIDIArp will continue to arpeggiate (in various patterns and at 
various tempos) the note data output of one or more interfaced 
MIDI instruments or any other MIDI-Manager-compatible ap- 
plications, desk accessories, or drivers. 


Where to Get the MIDI Manager 

The MIDI manager is currently available to developers 
through APDA and may possibly be shipped with future System 
Disks. The MIDIArp sample application (and several other 
samples) are included on the APDA disk as well. Although there 
are no MIDI-Manager-compatible third party applications avail- 
able at the time of this writing, various Macintosh MIDI devel- 
opers are currently working toward MIDI Manager compatibil- 
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ity, and itis likely that many third party application packages will 
become available in the near future. 

[The full listing is not included due to licensing concerns; 
you may however get the MIDI manger and PatchBay on the 
source code disk for this issue, #50. -ed] 


/* 

For commented, properly 

formatted, and complete 

Source code, please refer 

to the MacTutor source 

listing disk for this issue. 
*/ 
/*** MIDIArp.h **£/ 
def ine mainDialogID 2000 
"def ine quitID 1 
Sdefine patternPromptID 2 
def ine patternUpID 3 
def ine patternDownID 
зде? ine patternUpDownID 
8def ine patternDownUpID 
зде? ine patternRandomID 
8Sdef ine speedPromptID 
зде? ine speedVeryFastID 
8def ine speedFastID 1g 
def ine speedMediumID 11 
8def ine speedSlowID 12 
Sdefine speedVerySlowID 13 


oman nul» 


Sdefine arpAlertBoxID 12345 
Sdefine arpAboutAlertID 13554 
def ine portResType ‘port’ 


def ine timePortResInfoID 128 
define inputPortResInfoID 129 
def ine outputPortResInfoID 130 
def ine noteTblSize 32 


ttdef ine goingUp 1 
Sdef ine goingDown Ü 
8def ine speedVeryFast 50 
tdef ine speedFast 100 
tidef ine speedMedium 200 
tdef ine speedS low 300 


8def ine speedVerySlow 500 

зде? ine noteDuretion  CArpGlobals.Tempo * 0.95) 
8def ine arpClientID 'MArp' 

Sdefine arpicon 128 


Sdefine timePortID ‘Atim’ 
Sdefine inputPortID ‘Bin ' 
8def ine outputPortID “Сом%” 


8def ine keyOnOf fPacketSize9 
Sdefine stdPacketFlags 0 
Sdefine flagsTimeStampMask 0хТҒ 
Sdefine nol imeBaseRefNum 


8def ine noClient 4 f 
зде? ine noReadHook ØL 
8def ine noTimeProc ØL 
Sdef ine zeroTime ØL 
Sdefine zeroPer iod ØL 
8def ine refCond ØL 


8def ine timePortBuffSize ØL 
def ine inputPortBuffSize 2048 
def ine outputPor tBuffSizeðL 


typedef struct 

( unsigned char Channel, 
unsigned char Note; 
unsigned char Velocity; 
unsigned char Dummy; 

) NoteInfo; 

typedef struct 


( short Locked; NoteInfo NoteTbl (noteTb1Size]; 
long  NoteIndex; short NumNotes; NoteInfo 
LastNote; short ArpPattern; short ArpDi- 
rection; long Tempo; long NextNoteOnTime; 
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short InputRefNum; short OutputRef Num; 
short TimeRefNum; 
) ArpParams; 


/***x*xxxx xxxxxx 


MIDIArp.c 
ХХХ ХХХ ХАЖ / 
// Include Standard Mac Headers 
*include «MIDI.h» 
include "MIDIDefs.h"^ 
include "MIDIArp.h^ 


DialogPtr GMainDialog; 
ArpParams ArpGlobals; 
short  GCurSpeedID; 
Boolean GManualPatch; 
Boolean GDone = false; 
char GMIDIMgrVerStr (256); 


mainc) 


InitThings(); 
Arplnit(); 
StartDialog(); 
RunDialog(); 
ArpClose(); 

) StopDialog(); 


void InitThings(void) 
( 


FlushEvents(everuEvent, 0); InitGraf C&qd. thePort); 


InitFonts(); 
InitWindows(); 

Ini tMenusC ); 
TEInit(); 
InitDialogsCNULL ); 
InitCursor(); 


Handle MenuBar = GetNewMBar (menuBar ); 

Se tMenuBar (MenuBar ); 
DisposHandleCMenuBar ); 
AddResMenu(GetMHandleCappleMenu), ‘DRVR’); 
DrawMenuBar ( >; 


seed(); // Rand Num Generator 


void ArpInit(void) 
( 


MIDIPortParams Init; 
Handle TheIconHnd] ; 
OSErr TheErr; 

long MIDIMgrVerNum; 
char CStrBuf 1[256]; 


MIDIMgrVerNum = SndDispVersion(midiToolNum); 
1f (MIDIMgrVerNum == 0) 
( 


ArpAlert(“The MIDI Manage is not installed! 
Aborting...”); 
ExitToShe11C); 


else 
StdMacVerNumToStrCMIDIMgrVerNum, GMIDIMgrVerStr); 
sprintf CCStrBuf 1, "MIDI Manager Version $s”, 


GMIDIMgrVerStr); 
ArpAlert(CStrBuf 1); 
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ThelconHnd] = GetResource(‘ICN®’, arpIcon); 

TheErr = MIDISignInCarpClientID, refCond, 
TheIconHndl, *\pMIDIArp”); 

if (TheErr) 


ArpAlert(“Trouble signing MIDIArp into MIDI 
Manager! Aborting...”); 
ExitToShel1(); 


GManualPatch = true; 


Init.portID = timePortID; 
Init.portType = midiPortTypeT ime; 
Init.timeBase = noTimeBaseRefNum; 
Init.readHook = noReadHook; 
Init.initClock.sync = midiInternalSync; 
Init.initClock.curTime = zeroTime; 
Init.initClock.format = midiFormatMSec; 
Init.refCon = SetCurrentA5C); 
C2PStrCpyC^TimeBase", Init.name); 
TheErr = MIDIAddPort(erpClientID, timePortBuffSize, 
&CArpGlobals.TimeRefNum), &Init); 


C (TheErr == midiVConnectMade) 
GManualPatch = false; 
else if (TheErr == memFullErr) 


ArpAlertC*Not enough room in 
heap zone to add time 
port! Aborting...”); 

MIDISignOutCarpClientID); 

ExitToShe11C); 


Init.portID = inputPortID; 

Init.portType = midiPortTypeInput; 

Init.timeBase = ArpGlobals.TimeRefNum; 

Init.offsetTime = midiGetCurrent; 

Init.readHook = (Ptr) ArpReader; 

Init.refCon = SetCurrentA5C); 

C2PStrCpyC^InputPort^, Init.name); 

TheErr = MIDIAddPortCarpClientID, inputPortBuffSize, 
&CArpGlobals.InputRefNum), &Init); 


if (TheErr == midiVConnectMade) 
GManualPatch = false; 
else if (TheErr == memFullErr) 


ArpAlert(“Not enough room in heap zone to add input 
port! Aborting...”); 

MIDISignOutCarpCl ient ID; 

ExitToShe11C); 


Init.portID = outputPortID; 

Init.portType = midiPortTypeOutput ; 

Init.timeBase = ArpGlobals. TimeRefNum; 

Init.offsetTime = midiGetCurrent; 

Init.readHook = NULL; 

Init.refCon = &ArpGlobals; 

C2PStrCpyC*OutputPort^, Init.name); 

TheErr = MIDIAddPortCarpClientID, outputPortBuffSize, 
&CArpGlobals.OutputRefNum), &Init); 


1f (TheErr == midiVConnectMade)( 
GManualPatch = false; 


or if (TheErr == memFullErr) 
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) 


) 


ArpAlert(“Not enough room in heap zone to add output 
port! Aborting...^); 
MIDISignOutCarpC! ient ID); 

) ExitToShel1(); 


if (GManualPatch) 
PatchPorts(); 


ArpGlobals.Locked = false; 
ArpGlobals.NumNotes = 0; 
ArpGlobals.ArpPattern = patternUpDownID; 
ArpGlobals. Tempo = speedMedium; 
GCurSpeedID = speedMediumID; 


MIOIStartTimeCArpGlobals.TimeRef Num); 


С” StartDialog(void) 


GMainDialog = GetNewDialog(mainDialogID, 
NULL, (WindowPtr) -1); 
SetPort(GMainDialog); 


ChangeState(GMainDialog, ArpGlobals.ArpPattern == 
patternUpID, patternUpID); 
ChangeState(GMainDialog, ArpGlobals.ArpPattern == 
patternDownID, patternDownID); 
ChangeState(GMainDialog, ArpGlobals.ArpPattern == 
patternUpDownID, patternUpDownID); 
ChangeState(GMainDialog, ArpGlobals.ArpPattern == 
patternDownUpID, patternDownUp 102; 
ChangeState(GMainDialog, ArpGlobals.ArpPattern == 
patternRandomID, patternRandomID); 


ChangeState(GMainDialog, GCurSpeedID == 
speedVeryFastID, speedVeryFastID); 

ChangeState(GMainDialog, GCurSpeedID == speedFastID, 
speedFastID); 

ChangeStateCGMainDialog, GCurSpeedID == 
speedMediumID, speedMediumID); 

ChangeState(GMainDialog, GCurSpeedID == speedSlowID, 
speedSlowID); 

ChangeState(GMainDialog, GCurSpeedID == 
speedVerySlowID, speedVerySlowID); 


ShowWindowCGMainDialog); 
StdAdjustDLOGLocat ion(GMainDialog); 


се RunDialog(void) 


OSErr TheErr = noErr; 
short ItemHit; 
EventRecordAnEvent; 
WindowPtr WhichWindow; 
Rect Boundry; 
MIDIPortInfoHd) PortInfoH; 
GrafPtr SavePort; 


while (!GDone) { 
if (MIDIWorldChangedCarpC1 ient ID?) 


PortInfoH = MIDIGetPortInfoCarpClientID, timePortID); 
16 ((**PortInfoH).timeBase.clientID != noClient) 


MIDISetSyncCArpGlobals.TimeRefNum, midiExternalSync?; 


else 


MIDISetSyncCArpGlobals.TimeRefNum, midiInternalSync); 
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DisposHandle( (Handle) PortInfoH); 
C (WaitNextEvent(everuEvent,kAnEvent, updatePeriod, NULL)) 


1f (CAnEvent.what == keyDown) && CAnEvent .modif iers 
& cndKey2) 


AdjustMenus(); 
DoMenuCommand(MenuKeyCAnEvent.message & charCodeMask ) 


); 
) 
1f (IsDialogEvent(&AnEvent)) 
C (AnEvent.what == updateEvt) 


GetPortC&SavePort); 

SetPort((GrafPtr) AnEvent .message?; 
StdHiliteButtonCGMainDialog, quitID); 
SetPort(SavePort); 


if (AnEvent.what == keyDown && 
(CAnEvent .message & charCodeMask) 
== charEnterKey)) 


GDone = true; 


else if ( 
Co ee &GMainDialog, &ItemHit)) 


switch (ItemHit) 


case quitID: 
GDone = true; 
break; 


case 
patternUpID: 
case 
patternDownID: 
case 
patternUpDownID: 
case 
patternDownUp ID: 
case 
patternRandomID: 
SwitchRedioCGMainDialog, &CArpGlobals.ArpPettern), 
ItemHit); 
break; 


case 
speedVeryFast ID: 
ArpGlobals. Tempo = speedVeryFest; 
SwitchRadioCGMainDialog, &GCurSpeedID, ItemHit); 
break; 


case 
speedFastID: 
ArpGlobals.Tempo = speedFast; 
SwitchRadioCGMainDialog,&GCurSpeedID, ItemHit); 
break; 


case 
speedMediumID: 
ArpGlobals.Tempo = speedMedium; 
SwitchRadioCGMainDialog, &GCurSpeedID, ItemHit); 
break; 


case 


speedS lowID: 
ArpGlobals. Tempo = speeds low; 
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SwitchRadio(GMainDialog, &GCurSpeedID, ItemHit); 
break; 


case 
speedVeryS lowID: 
ArpGlobals. Tempo = speedVerySlow; 
SwitchRadio(GMainDialog, &GCurSpeedID, ItemHit); 


break; 
default: 
SysBeep(2); 
break; 
) 
else ( 


"ub tch CKAnEvent . what) 


case mouseDown: 
suwitch(FindWindowCAnEvent .where, 
Coe ) 


case 
inMenuBar : 
AdjustMenus(C); 
DoMenuCommand( 
MenuSelect(AnEvent.where)); 
break; 


case 
inSusWindow: 
SustemClick(&AnEvent, WhichWindow); 


break; 
case 
inContent: 
с CWhichWindow != FrontWindow()) 


SelectWindow(WhichWindow); 
AdjustMenus(); 


break; 
case 
inGoAway: 


1f (CTrackGoAwayCWhichWindow, AnEvent .where)) 


GDone = true; 


break; 
case 
inDrag: 
SetRect(&Boundry, 4, 24, 
qd.screenBits.bounds.right - 4, 
qd.screenBits.bounds.bottom - 4); 


DragWindowCWhichWindow, AnEvent . where, &Boundry); 


break; 
default: 
break; 


break; 


default: 
break; 


) 
) 
) 
) 
) 


void ArpClose(void) 
Ш (GManualPatch) 
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SavePatch(timePortID, timePortResInfoID, “timePortInfo”); 
SavePatchCinputPortID, inputPortResInfoID, 


*inputPortInfo^); 


SavePatchCoutputPortID, outputPortResInfoID, 


*outputPortInfo^); 


| MIDISignOut(arpClientID); 


void StopDialog(void) 
StdSaveDLOGLocation(GMainDialog, mainDialogID); 


HideWindow(GMainDialog); 
DisposDialog(GMainDialog); 


pascal short 


ArpReader(MIDIPacket *ThePacketPtr, long TheRef Con) 
( 


long SysA5 = SetA5(TheRefCon); 
short RetVal = midiMorePacket, i, j; 


1f(ArpGlobals.Locked) 
RetVal = midiKeepPacket; 


else if С ThePacketPtr->flags == stdPacketFlags 


&& CCThePacketPtr->data[@) & statusMask) 
== keyOn || (ThePacketPtr->data[@] 
& statusMask) == keyOff )) 


RetVal = midiMorePacket; 
if (CIhePacketPtr-»data[0] & statusMask) 


== keyOn && ThePacketPtr->data[2] != zeroVelo) 
for (i70; i«ArpGlobals.NumNotes; i++) 


if (ThePacketPtr->data{1] <= 
ArpGlobals.NoteTb1(i).Note) 


break; 


) 
ыы а pi; j- 


ArpGlobals. 

Notelbl[j].Channel = ArpGlobals.NoteTb1[j~1].Channel; 
ArpGlobals. 

NoteTb1[jl.Note = ArpGlobals.NoteTb1[j-1].Note; 
ArpGlobals. 

NoteTb1[j].Velocity = ArpGlobals .NoteTb1[j-1). 


) Velocitu; 
ArpGlobals.NoteTbl[il.Channe] = ThePacketPtr-,data[0] 
& channelMask; 


ArpGlobals.NoteTbl[il.Note = ThePacketPtr-»data( 11; 
ArpGlobals.NoteTb1[il].Velocity = ThePacketPtr-»data[2]1; 


1fCArpGlobals.NumNotes < noteTb1Size) 
ArpGlobals.NumNotes**; 
юе == 1) 


ArpGlobals.NextNoteOnTime = ThePacketPtr->tStamp; 
ArplimeProc(ThePacketPtr-,tStamp, TheRefCon); 


) 
else if ((ThePecketPtr-»dete[0] & 


statusMask) == keyOff || (ThePacketPtr-»data[0] & 
statusMask) == key0n) 
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for (i=0; i« ArpGlobals.NumNotes; i++) 


if(CArpGlobals .NoteTb1[i].Channel == 
(ThePacketPtr->data[@] & channe]Mask )) 
М. (ArpGlobals.NoteTbl1[il.Note == 
ThePacke tPtr->datal1])) 


break; 
) 
с (i < ArpGlobals.NumNotes) 


Іт (/*izi*/; i<ArpGlobals.NumNotes-1; i++) 


ArpGlobals.NoteTb1[il.Chennel = 
ArpGlobals.NoteTb1[i*1].Channel; 
ArpGlobals.NoteTbl[il.Note = 
ArpGlobals.NoteTb1[i*1].Note; 
ArpGlobals.NoteTb1[il.Velocity = 
ArpGlobals.NoteTb1[i*1].Velocity; 


) 
ArpGlobals.NumNotes-; 


) 
) 


SetA5(SysA5); 
return(RetVal); 


ert void ArpTimeProcClong , long TheRefCon) 


long SysA5 = SetA5CTheRef Con); 
int i; 
MIDIPacket TheMIDIPacket; 


ArpGlobals.Locked = 1; 
1f CArpGlobals.NumNotes == 0) 


MIDIWekeUpCArpGlobals.TimeRefNum, zeroTime, 
zeroPeriod, поТітеРгос); 


else 
( 


BumpNoteTableIndex(); 
1f CArpGlobals.NoteTb] [ArpGlobals.NotelIndex] 
== ArpGlobals.LastNote) 


BumpNoteTableIndex(); 


ArpGlobals.LastNote = ArpGlobals.NoteTbII 
ArpGlobals.NoteIndex]; 


TheMIDIPacket.flags = stdPacketF lags; 
TheMIDIPacket.len = keyOn0f f PacketSize; 


i = ArpGlobals.NoteIndex; 
TheMIDIPacket.tStamp = ArpGlobals.NextNoteOnT ime; 
TheMIDIPacket.data(0] = ArpGlobals.NoteTb1[i]. 

Channel | keyOn; 
TheMIDIPacket.date[1] = ArpGlobals.NoteTb1(i].Note; 
TheMIDIPacket.data[2] = ArpGlobels.NoteTb1ti).Velocity; 
MIDIWritePecketCArpGlobals.OutputRefNum, &TheMIDIPacket); 


TheMIOIPacket.tStamp += noteDuration; 
TheMIDIPacket.data[0] -= 0x10; 
MIDIWritePacketCArpGlobals.OutputRefNum, &TheMIDIPacket); 
ArpGlobals.NextNoteOnTime += ArpGlobals.Tempo; 


MIDIWakeUpCArpGlobals. TimeRefNum, 
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ArpGlobals.NextNoteOnTime - ArpGlobals.Tempo/2, 
zeroPeriod, (ProcPtr) ArpTimeProc); 


ArpGlobals.Locked = false; 
SetA5(SysA5); 


void BumpNoteTableIndex(Cvoid) 


1f CArpGlobals.NumNotes == 1) 
ArpGlobals.NoteIndex = 0; 
else 
switch(ArpGlobals.ArpPattern) 
сазе patternUpID: 
if CArpGlobals .NoteIndex >= ArpGlobels. 
NumNotes- 1) 
ArpGlobals.NoteIndex = 0; 
else 
ArpGlobals.NoteIndex**; 
break; 
case petternUpDownID: 


case patternDownUpID: 
1f CArpGlobals.ArpDirection == goingUp) 


1f CArpGlobals.Notelndex > 
ArpGlobals.NumNotes-1) 


ArpGlobals.Notelndex = ArpGlobals.NumNotes-1; 
ArpGlobals.ArpDirection = goingDown; 


else if CArpGlobals.NoteIndex == 
ArpGlobals.NumNotes- 1) 


ArpGlobals .NoteIndex-; 
ArpGlobals.ArpDirection = goingDown; 


else 


ArpGlobals.NoteIndex**; 
) 


else 
1f CArpGlobals.NoteIndex < 0) 


ArpGlobals.NoteIndex = 0; 
ArpGlobals.ArpDirection = goingUp; 


) 
"nn 1f CArpGlobals.NoteIndex == 0) 


ArpGlobals.NoteIndex**; 
ArpGlobals.ArpDirection = goingUp; 


else 


ArpGlobals.NoteIndex-; 
break; 


case patternDownID: 
ч (ArpGlobals.Notelndex <= 0) 
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ArpGlobals.NoteIndex = ArpGlobals. 
NumNotes- 1; 


else 
ArpGlobals .NoteIndex-; 
break; 


case patternRandomID: 
ArpGlobals .Note Index 
= ChooseCArpGlobals.NumNotes); 
break; 


) 
) 


"du PatchPortsCvoid) 


MIDIPortInfoHdl PortInfoH; 
MIDIPortInfoPtr PortInfoP; 
short i, TheErr; 


PortInfoH = CMIDIPortInfoHd1) 
GetResourceCportResType, timePortResInfoID); 
1f (PortInfoH == NULL) 


ReportResError(*GetResource(portResType, 
tinePortResInfoID2*); 


HLock( (Handle) PortInfoH); 
PortInfoP = *PortInfoH; 
if (GetHandleSizeCCHendle) PortInfoH) != 0) 


1f (PortInfoP-»timeBase.clientID != noClient) 


TheErr = MIDIConnectTimeCPortInfoP-» 
timeBase .clientID, PortInfoP-» 
timeBase.portID, arpClientID, timePortID); 

CTheErr != midiVConnectErr) 


MIDISetSyncCArpGlobals.TimeRefNum, 
midiExternalSync); 


) 
for (i=0; i<PortInfoP->numConnects; i++) 


MIDIConnectTimeCarpClientID, timePortID, 
PortInfoP-»cList[i].clientID, 
PortInfoP-»cList(i].portID); 


) 

HUnlockCCHandle) PortInfoH); 

ReleaseResource( (Handle) PortInfoH); 
ReportResError( “PatchPorts/Re leaseResource( )”); 


PortInfoH = CMIDIPortInfoHd]) 
GetResource(por tResType, inputPor tResInfoID); 
1f (PortInfoH == NULL) 


Repor tResError (“PatchPor ts/Ge tResource( )”); 


HLockCCHandle? PortInfoH); 
PortInfoP = *PortInfoH; 
с (GetHandleSize((Handle) PortInfoH) != 0) 


бог (i20; i<PortInfoP->numConnects; i++) 
MIDIConnectDataCarpClientID, inputPortID, 


PortInfoP-»cList[il.clientID, 
PortInfoP-»cList[il.portID); 


@ The Best of MacTutor, Vol. 5 


) 

HUnlockCCHandle) PortInfoH); 
ReleaseResourceCCHendle) PortInfoH); 
ReportResError(*PatchPorts/GetResource(2^); 


PortInfoH = CMIDIPortInfoHd!) 
GetResource(portResType, outputPortResInfoID); 
if (PortInfoH == NULL) 


ReportResError(“PatchPorts/GetResource()”); 


HLock(€ (Handle) PortInfoH); 
PortInfoP = *PortInfoH; 
if (GetHandleSizeCCHandle) PortInfoH) != 0) 


forCi=0; i«PortInfoP-»numConnects; i++) 


MIDIConnectDataCarpClientID, outputPortID, 
PortInfoP-cList(i].clientID, 
PortInfoP->cListlil].portID); 


) 

HUnlockCCHandle) PortInfoH); 

ReleaseResource( (Handle) PortInfoH); 

Repor tResError( “PatchPorts/Re leaseResource( )”); 


) 


void SavePatch(OSTupe PortID, short PortInfoResID, char 


“SOS Sa Sapa 


Handle Por tResH; 
CursHandle WatchCurs; 


WatchCurs = GetCursor(watchCursor); 
HLock( (Handle) WatchCurs); 
SetCursor(*WatchCurs); 
HUnlock((Handle) WatchCurs); 


PortResH = GetResource(por tResType, 
PortInfoResID); 

Repor tResError( “SavePatch/GetResource( 2”); 

RaveResource(Por tResH); 

Repor tResError( “SavePatch/RmveResource( ) 
(make sure disk is unlocked)’ ); 

DisposHendleCPortResH); 

UpdateResF i leCCurResF і1ес )); 

Repor tResError( “SavePatch/UpdateResF i leC) 
(make sure disk is unlocked)”); 


PortResH = (Handle) MIDIGetPortInfo( 
arpClientID, PortID); 


addresource(PortResH, portResType, PortInfoResID, 
Por tInfoResName ); 

Repor tResError( “SavePatch/addresource()”); 

Wr iteResource(Por tResH); 

ReportResError(^SavePatch/Wr i teResource( ) 
(make sure disk is unlocked)’); 

UpdateResF i le(CurResFile()); 

ReportResError( “SavePatch/UpdateResF i le( > 
(make sure disk is unlocked)”); 

Re leaseResource(Por tResH); 

ReportResError (“SavePatch/Re leaseResource( ) 
(make sure disk is unlocked)”); 

InitCursor(); 


) 


void Terminate(void) 


MIDISignOut(arpClientID); 
StopDialog(); 
ExitToShel1(); 


Advanced Mac ing 


Inside Controls 


[Ken Earle has been programming the Mac in C for about 
two years and still thinks it is fun. In between Mac contracts, he 
waits for the price of Finale to drop...] 

If the Control Manager chapter of Inside Macintosh has you 
resignedly scrolling back to reread QuickDraw, here's a different 
point of view that might help. Or if scroll bars have lost their thrill 
and you're looking for a new toy, absorbing the code from this 
article will let you design your own custom controllable 
rotary-indicator digital-readout gizmos, guaranteeing hours of 
harmless entertainment. 

First we'll take a look at implementing meters (aw, you 
guessed) in a way that's functionally very close to the Control 
Manager (see the listings for Meter.h and Meter.c). Then, after a 
strategy session on scroll bars, you'll be ready for MeterTest, an 
application with fully—functional scroll bars and windows that 
can serve asa design rig for meters or as a skeleton for something 
grander (see MeterMain.c). 

If you're not using Think C, you'll need to at least include 
the standard Mac header files, and check usage of the QuickDraw 
global ‘thePort’ (called ‘qd.thePort’ in MPW C). 


The Meter Manager 

I don't know about you, but if I'm given the choice between 
a detailed description of a routine and the source code for it, I'd 
rather have the source code. Especially for those darn scroll bars, 
where, as Ted Nelson might put it, everything gets deeply 
intertwingled. To show how the Control Manager calls work on 
the inside and still end up with relatively useful code, let's take 
ashotatcreating a cousin of thc scroll bar, namely something like 
that nifty meter on page 312 о: 'nside Macintosh Volume 1. To 
better illustrate what the Control Manager does, the approach 
used is not to write a CDEF but rather to imitate most of the 
Control Manager routines, with Meters replacing Controls. The 
variations are minor enough that you should be able to get a good 
idea of what a “Control” routine does by looking at the corre- 
sponding “Meter” routine. For example, if you're interested in 
TrackControl(Q, take a look at TrackMeter() in the listing for 
Meter.c. 

The routines in Meter.c do not duplicate all of the Control 
Manager's functions (but enough, I hope), and are virtually 
guaranteed not to resemble Apple's source code except in func- 
tionality since I didn't peek at it, honest. Meter.c is meant to be 
read with Inside Macintosh on your lap and should be otherwise 
self-explanatory, provided you introduce yourself to what a 
meter is first. 


Prepare To Make Your Meter 


Figure 1 shows a typical meter. It has a needle that wiggles | 
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around in response to a 
continual input, a set 
point indicator that can 
be used for an alarm or 
for closed-loop control, 
four up and down “ar- 
rows" to move the set 
point around, a digital 
display, a title, and some 
background drawing to 
make it look like a meter. 
The most important dif- 
ference between a meter 
and a scroll bar is that a 
meter doesn't have a true 
thumb— the set point 
indicator would be the 


digital display 


Fourth Meter 


Figure 1. A Typical natural candidate, but itis 
Meter too small and slippery a 
target to be picked up and 


dragged around, especially if itis used for something like control- 
ling the temperature in a nuclear reactor. Instead, meters have a 
“background” part; a mouse down in anything except the up and 
down arrows will cause FindMeter() to return a part code for the 
background, and TrackMeter() will switch the digital display 
from the current input value to the set point value. For a look 
inside the scroll bar thumb see Where's the thumb?" below. 
Meters keep track of two values at once; the “meterValue”, 
which corresponds to a regular “сопітоГУаше”, represents the set 
point indicator which is under the user's control by means of the 
up and down arrows, and the *needleValue" is the current input 
to the meter and of course drives the ever-wandering needle. The 
needle has no analog (bad pun intended) in a regular control. 
Meters can be any size above a reasonable minimum, but 
their proportions are fixed since they are delicate creatures to 
draw ( the dial looks funny if it isn't round). You supply the top, 
left, and right for a new meter, and NewMeter() calculates the 
bottom for you. Many aspects of a meter's appearance can be 
modified by playing with the #defined constants at the top of the 
Meter.c listing, but for radical changes you'll want to dig into the 
details of CreateMeterBackground(), DrawNeedle(), etc. I like to 
think I’ve deliberately left lots of room for improvement... 
Although you can treat meters mostly the same way as scroll 
bars in an application, there are two important differences. First, 
the meter needle usually needs to be driven constantly, so you'll 
probably want to call SetNeedleValue() at the top of your main 
event loop—you'll see an example of this in MeterMain.c. And 
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second, meters attach themselves as a linked list to their win- 
dow's refCon field, in the same way that controls attach them- 
selves to the window’s controlList field. If you're already using 
this field to hold a reference to your own data structure, you 
should add a long int field “meterRef” to your data structure and 
replace the references in Meter.c to 


_ CMeterHandle)(wPk-refCon) 
with something like 


(Me terHandle)(myDataStructurePointer->meterRef ). 


Scroll Bars and Drawing 

Scroll bars by themselves just keep track of the value of one 
integer, and show you a rough indication of how big it is relative 
to a maximum and minimum. What you do with that value is up 
to you. The code in MeterMain.c demonstrates in a general way 
how to use scroll bars for controlling the position of fixed-size 
documents that contain graphics within fully-functional win- 
dows. Meters are used for the graphics, and when you build all of 
the listings into the application MeterTest you'll also have a tool 
for designing meters (see About MeterTest below). 

The key to tying scroll bars, windows, and drawing together 
is to introduce another system of coordinates (as if local and 
global weren't enough). Think of the graphics as being attached 
beneath the window to a piece of paper which we'll call the 
document. "Document" coordinates are for that piece of paper, 
running from 0,0 at left top down to ‘page width’, ‘page height’ 
at right bottom, and coincide with unscrolled coordinates when 
no scrolling has taken place. These numbers are usually in pixels, 
since they then describe positions in the grafPort directly. 

Scroll bars are used to relate local and document coordinates 
in the natural way that comes about if you think of dropping the 
window on top of the document. The scroll bar minimums are set 
to Zero, corresponding to the top left of the document. The scroll 
bar values record the horizontal and vertical coordinates of the 
top left of the window in document coordinates (which are 
always at least as large as local coordinates). The scroll bar 
maximums are equal to the amount of the document left unseen, 
so the vertical maximum for example is equal to Document 
Height less the PortRect Height less the 15 pixels covered by the 
horizontal scroll bar. To put it another way, see Figure 2. 

The overall strategy is to always draw in document coordi- 
nates by taking care of scrolling before the low-level drawing 
routines are called. Done properly, your drawing routines can 
pretend that they are always drawing to a giant screen that shows 
the whole (unscrolled) document at once. “Taking care of scroll- 
ing" is very easy. Before doing any drawing, shift the whole 
window into document coordinates by means of 
SetOrigin(hBarValue, vBarValue), and shift the clipping region 
too with OffsetRgn(thePort->clipRgn, hBarValue, vBar- 
Value)—then shift back when you’re done. When you’re deci- 
phering where the mouse is, local points from GetMouse() can be 
translated to document points by adding the scroll bar values to 
the appropriate coordinates (see DocToLocal()). 

Your drawing routines will draw to the right place if they 
take a point or rectangle in document coordinates to start from, 
and then draw relative to the point or rectangle without referring 
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top left of window = Oh, Ov in local coord's; 
horizontal scroll value, vertical scroll value 
in document coord's 


viewable window height = thePort-»portRect.bottom 
- thePort->portRect.top - SCROLLSIZE m 
in either coordinate system 


Bottom of viewable window content = vertical scroll 
value + viewable window height in document coord's 


Vertical scroll bar maximum z bottom of document 
- viewable window height, ie the amount of the 
document left unseen. The window title bar and the 
scroll bars cover the document 


bottom right of document = 576h, 720v (8" x 10") 


Figure 2. Scroll Bar Values 


to the scroll bars. For example, the body of a function to draw a 
straight horizontal line could look like 


(MoveToCdocPoint.h, docPoint.v); 
LineCwidthInPixels, 0);) 
However, something like 


MoveToCdocPoint.h + hBarValue, docPoint.v + v Ваг - 
Value); ; | ВА | 
probably won't do what you intended, since it is trying to 


shift from local to document coordinates, but that's already been 
done beforehand. If you need to refer to the window frame, the 
left edge of the window is still at thePort->portRect.left on the 
screen, but remember that this value isn't necessarily zero. 

Drawing needs to be done whenever the user wants some- 
thing new (eg mouse down with a "pencil" tool, or 
<Command>-drag to resize a meter іп MeterTest), and when 
events cause a hidden part of the document to be exposed (eg 
activating a different window, or scrolling). This redrawing as 
opposed to original drawing can all be handled by one routine, 
and this same routine can even draw to the clipboard or printer if 
you plan ahead. The strategy here is to: determine what part of the 
window necds redrawing; shift to document coordinates; and 
draw only those objects that have been newly exposed by calling 
the low-level drawing routines for those objects. UpdateCon- 
tents() is the redrawing function in MeterMain.c. 

The easiest way to keep track of what part of the window 
needs redrawing is to use a global region and set this region to the 
appropriate area just before calling the redraw function. If you 
glance through MeterMain.c you'll see that the region up- 
dateRgn is always set just before calling UpdateContents(). In 
principle the updateRgn can always be figured out exactly (see eg 
DoGrowWindow() and ScrollProc()), but sometimes it is ac- 
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ceptably fast to just cop out by invalidating the whole window 
and letting the generated update event take care of the drawing 
(see DoZoomWindow0, and “case updateEvt” in main()). 

I first ran into the idea of using document coordinates and a 
global update region in “Hidden Powers of the Macintosh” by 
Christopher Morgan (The Waite Group), still one of the best 
introductions to programming the Mac in spite of all the code 
being in Pascal. 

The redrawing for the arrow and paging parts of scroll bars 
is done in MeterMain.c by the function ScrollProc(), where both 
the moving of the screen image and the accumulation of the 
newly exposed region are managed by a single call to 
ScrollRect(). You could if you prefer handle paging by invalidat- 
ing the whole window (less scroll bars) and calling UpdateCon- 
tents()—this is faster, but less visually appealing. 

That just leaves the scroll bar thumb. I could have made it 
real easy for you, but some people just can’t leave well enough 
alone.... 


Where's the thumb? 

If you call TrackControl() with no action procedure in 
response to a mouse down in a scroll bar thumb, everything is 
taken care of for you. After the call, you just redraw the window 
if the new control setting differs from the old one. You can even 
get fancy and call ScrollRect() and UpdateContents() if the move 
was a small one, or invalidate the whole window if it was a biggy. 

One thing you can't do this way, however, is keep track of 
where the thumbis while the user is dragging it to and fro. In order 
to do this you have to know the "potential" new control value for 
each new mouse position, but not even TrackControl() bothers to 
figure this out. It just drags an outline of the thumb around 
without regard for value, and only calculates a new value when 
the mouse button is released. You could write an action proce- 
dure for TrackControl() that figures out where the thumb is, but 
in the spirit of getting inside things I have written a replacement 
for TrackControl() to be called for the thumb. ThumbControl() in 
MeterMain.c does all that TrackControl() does for the thumb, 
and also calculates the potential new control value for you (as 
well as the thumb's physical position). You can insert your 
custom routine calls at the places marked in the code, or modify 
the function to accept pointers to functions if you can't stand 
inelegance. 

While you could use this approach to place a page number 
directly inside the thumb, the approach used by WriteNow for 
example of putting the page number alongside a scroll bar is 
simpler and also better—try putting a four-digit page number 
inside the scroll box! MeterMain.c by the way shows how to put 
anumeric display nextto a scroll bar, something that's especially 
useful when designing or debugging. 


About MeterTest 
If you build an application from the files in this article 
according to the instructions at the top of the listing for 
MeterMain.c you'll have MeterTest, which sums everything up 
by presenting meters as graphic objects inside of windows with 
scroll bars. The underlying documents which contain the meters 
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are fixed in size (8" by 10"), and all the usual scrolling and 
window functions are implemented in a general way except for 
the lowest-level drawing routines. 

MeterTest can also serve as a test rig for modifying the 
appearance and function of meters. Y ou'll have use an edit-and- 
recompile approach, but fortunately MeterTest is small and 
Think C is fast. Many changes can be made by altering the 
#defines at the top of Meter.c, but others will require changing the 
routines that create the meter’s background and draw the other 
parts. The titles for the four default meters and two windows are 
at the top of MeterMain.c, and other standard parameters for the 
meters are set inside the function MakeTwoMeters(). 

To move ameter around, Option-drag it. Command-drag on 
a meter to resize it constantly while the button is down. The 
display box at lower right of the window shows the horizontal and 
vertical scroll bar values unless you resize a meter, in which case 
it shows the meter width and height. Click on an up or down 
triangle in a meter to move the set point indicator up and down, 
or click anywhere else on a meter to change the meter’s display 
from the current needle input to the set point value. 


Bonus round 
In the accompanying code you’ll also find examples of 
simple animation, using integer tables to represent transcenden- 
tal functions, ring—shaped clipping, how to shadow any polygon, 
handling linked lists and pointers to functions...and after you’ve 
worked through it all, you'll never again be intimidated by a 
stupid thumb. 


Listing: Meter.h 


/*Meter.h - MeterRecord definition & interface function 
protoypes*/ 


/* special partCode for meter */ 
define inBackground 24 


struct MeterRecord 


struct MeterRecord **nextMeter; /* or NULL */ 


WindowPtr meterOwner ; 
Rect meterRect; /* includes title*/ 
Byte meterVis; 
Byte meterHilite; 
long meterValue, meterMin, meterMax, 
needleValue; 
/*ProcPtr meterAction; not implemented */ 
long mneterRf Con; 
char title[32]; /* pascal format, length byte first */ 
/* some additional fields not in a control record */ 
Rect incDownRect, incUpRect, 
pageDownRect, pageUpRect; 
Rect disp layRect; 
long displayDivisor; /* power of ten */ 
int needleShort, needleLong, halfNeedleWidth; 
int setShort, setLong, halfSetWidth; 
PicHandle backgroundH; 
PolyHandle incUpH, incDownH, pageUpH, pageDownH; 
Point dialCentre; 
long hasMeter ID; 


); 
typedef struct MeterRecord MeterRecord; 
typedef MeterRecord *MeterPtr; 
typedef MeterRecord **MeterHandle; 
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typedef void (*voidPtr)() ; 


/* Functions defined in Meter.c */ 

extern MeterHandleNewMeter(WindowPtr, Rect*, char*, 
Boolean, long, long, long, long); 

extern voidDisposeMeter(MeterHandle); 

extern voidKillMeters(WindowPtr); 

extern voidSetMTitle(MeterHandle, char*); 

extern voidGetMTitle(MeterHandle, char*); 

extern voidHideMeter(MeterHandle); 

extern void ShowMeterCMeterHandle); 

extern void DrawMeters(WindowPtr ); 

extern voidHiliteMeter(MeterHandle, int); 


extern int FindMeter(Point, WindowPtr, MeterHandle*); 
extern int TrackMeter(MeterHandle, Point, voidPtr); 
extern int TestMeter(MeterHandle, Point); 


extern void MoveMeter(MeterHandle, int, int); 
extern void DragMeter(MeterHandle, Point, Rect*, Rect*, int); 
extern voidSizeMeter(MeterHandle, int); 
/* note proportions are fixed */ 

extern voidSetMtrValueCMeterHandle, long); 
extern long GetMtrValueCMeterHandle); 
extern voidSetMtrMinCMeterHandle, long); 
extern long GetMtrMin(MeterHandle); 
extern voidSetMtrMaxCMeterHandle, long); 
extern long GetMtrMax(MeterHandle); 
extern void SetMRef ConCMeterHandle, long); 
extern long GetMRef ConCMeterHandle); 
/* note multiple actions procs not supported in this versiont/ 
extern void SetNeedleValue(MeterHandle, long); 
extern long GetNeedleValueCMeterHandle); 
extern long GetDisplayDivisor(MeterHandle); 
extern Boolean ValidMeter(MeterHandle); 
extern int — GetMaxTitlePixelsCMeterHandle); 
extern void MeterSnapshot(MeterHandle); 

/* draws to thePort rather than meter s owning window */ 
Listing: Meter.c 
/* Meter.c - display, drive & control a meter with set point. 
Useage: add 'Meter.c' to your project, and #include "Meter.h"^ 
in any file that refers to the functions below. Add ‘Math’ and 
"include «math.h» if you don’t hand-load the sineTable[]. 
- the main purpose here is to show how the Control Manager 
works, so we'll use functional equivalents of most of the 
Control Manager routines listed in Inside Macintosh vol 1 
pages 309 - 338 rather than creating a new kind of control. In 
general, “Control” in IM is replaced by “Meter” here; for 
example, if you're interested in how NewControl() works see 
NewMeter() below. See MeterProc() in MeterMain.c for an action 
procedure that is called by TrackMeter() to drive the set 
point indicator up and down. Fancy stuff requiring external 
user-defined resources is not included (no GetNewMeter()), nor 
is a default action Proc supported (always call TrackMeter() 
with your action Proc ог 01). Two other differences that no 
one should mind - all functions are ‘C’ rather than ‘Pascal’, 
and all value parameters are long. 
- meterValue refers to the set point value, which is normally 
under user control, and can be set by SetMtrValue(). 
- needleValue refers to current input to the meter, displayed 
by the needle and NOT normally under user's control, set bu 
SetNeedleValueC). 
- the digital display normally shows needleValue unless mouse 
is down in meter background (simple equiv of control “thumb”). 
- for a more detailed look at controlling what happens when 
mouse is in an indicator see ThumbControlC) in MeterMain.c. 
- the arrow and paging parts appear as small and large 
triangles (defined as polygons), with the standard part codes. 
- meter handles are linked to the owning windows’ refCon 
field. If you want to use this field for something else, 
change the refCon references below in NewMeter(), DisposeMe- 
ter(), KillMetersC?, DrawMeters(), and FindMeter(). 
*/ 
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/* Do not include Meter.h, but DO *include «MacHeaders? either 
explicitly here or by setting the "«MacHeaders?" option */ 


/* math.h is needed for sineTable(], otherwise hand-load it.*/ 
зде? ine .ERRORCHECK.. 

int errno; 

include «math.h» 


/* special partCode for meter, everything but the four up and 
down arrows. A meter has no true thumb - the set point 
indicator is a skinny rotating target, and too dangerous to 
grab if the meter is being used for closed-loop control. 
“Track and hilite the background” just means show the set 
point value in the display rather than the current needle 
value while the mouse is down. */ 

Sdefine inBackground 24 


define NULL ØL 
8def ine HASMETER ‘qwer’ /* arbitrary long ID, 
used by ValidMeter() */ 


/* Some "defines to vary the appearance of the meter. Since 
meters are complicated beasts to draw, be prepared to f ine- 
tune the drawing code as well if you explore different looks! 
*/ 
8def ine MINWIDTH 48/* min. usable meter width*/ 
8Sdef ine TVHRATIO 1400L 
/* black rounded rect height/width, times 1000 */ 
8define TITLEHEIGHT 24  /* height of title 
box below meter proper, plus 4 */ 
/* given width of meter = w, total height is Cw*TVHRATIO)/ 1000 
* TITLEHEIGHT */ 
Sdefine TEXTVOFFSET 4 /* to centre 12 pt 
text in the display box */ 
Sdefine INNERPCT 94L /* used for defining needle 
and set point lengths as а $ of dial radius */ 
define HALFSETWIDTH 1  /* half width of set 
point indicator */ 
/* redius of meter's 
little centre circle */ 
8def ine PGPOLYHEIGHT 30001. 
/* times 1000, keep it between 1000 and 3000 */ 
8def ine INCPOLYHEIGHT 2000L 
/* -POLYHEIGHT is ratio of height to width of set point 
contr! triangles times 1000 - try 1000, 1414, 1732,2000,3000. */ 
def ine NUMTICKS 11 /* number of major position ticks 
around circumference */ 
Sdefine NUMMINORTICKS 51 
NUMTICKS. */ 
Sdefine HALFNEEDLERATIO8 — /* dial radius/ 
HALFNEEDLERATIO = halfNeedleWidth */ 
Sdefine MINDIGITS 3 /* minimum number of 
digits to display */ 
"def ine MAXDIGITS 5  /* maximum number of 
digits to display */ 
/* The digital display will show at least MINDIGITS for small 
meters, and at most MAXDIGITS for large meters. See 
ShowValue(),AdjustDisplay(), and SetDisplayDivisor() for 
details. As a nicety, you should update the meter title to 
reflect the actual units displayed (eg if input is Volts and 
displayDivisor is 10, the meter name should be something like 
“Volts / 10^ */ 


Sdefine CENTRERADIUS 3 


/*NUMMINORTICKS includes 


static int sineTable(91]; /* set up by InitMeters() */ 


dad MeterRecord 


struct MeterRecord **nextMeter; /* or NULL */ 


WindowPtr meterOwner ; 

Rect meterRect; /* includes title */ 
Byte meterVis; 

Byte meterHilite; 

long meterValue, meterMin, 
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meterMax, needleValue; 
/*ProcPtr meterAction; - not implemented */ 


1ong meterRf Con; 
char title([32]; /* pascal format, length byte first */ 
/* some additional fields not in a control record */ 
Rect incDownRect, incUpRect, 
pageDownRect, pageUpRect; 
Rect displayRect; /* digital display */ 
Tong displayDivisor; /* power of ten */ 
int needleShort, needleLong, halfNeedleWidth; 
int setShort, setLong, halfSetWidth; 


PicHandle background; 
PolyHandle incUpH, incDownH, pageUpH, pageDownH; 
/* triangles */ 


void  AdjustDisplay(MeterHandle?; 
void SetDisplayDivisor(MeterHandle); 
void GetSinAndCosCint, long*, long*); 


/* New meter handles are linked to the window’s refCon field. 

Meter proportions are fixed; height is determined from width, 

and boundRect.bottom is ignored. There is no default action 

procedure. Titles are truncated on theright.*/ 

MeterHandleNewMeter(wPtr, boundRect, title, visible, 
neterValue, meterMin, meterMax,meterRfCon) 

WindowPtr  wPtr; 

Rect *boundRect; 

char *title; 


Point dialCentre; 
long hasMeterID; /* - HASMETER for a meter */ 


typedef struct MeterRecord MeterRecord; 
typedef MeterRecord *MeterPtr; 
typedef MeterRecord **MeterHandle; 


typedef void (*voidPtr)(); /*true C equiv. of procPtr */ 
/* Functions defined in this file */ 


/* External interface, mostly like Control Manager */ 
/* Control Manager equivalents */ 
MeterHandleNewMeter(WindowPtr, Rect*, char*, 
Boolean, long, long, long, long); 
void  DisposeMeter(MeterHandle); 
void KillMeters(WindowPtr); 
void SetMTitleCMeterHandle, char*); 
void  GetMTitleCMeterHandle, char*); 
void HideMeter(MeterHandle); 
void ShowMeter(MeterHandle); 
void DrawMetersCWindowPtr); 
void HiliteMeter(MeterHandle, int); 
int FindMeter(Point, WindowPtr, MeterHandle*); 
int TrackMeter(MeterHandle, Point, voidPtr); 
int TestMeter(MeterHandle, Point); 
void MoveMeter(MeterHandle, int, int); 
void DragMeter(MeterHandle, Point, Rect*,Rect*, int); 
void SizeMeter(MeterHandle, int); /* note 
proportions are fixed */ 
void SetMtrValue(MeterHandle, long); /* use 
this to move the set point */ 
long GetMtrValueCMeterHandle); 
void SetMtrMin(MeterHandle, long); 
long GetMtrMinCMeterHandle); 
void SetMtrMax(MeterHandle, long); 
long GetMtrMax(MeterHandle); 
void SetMRefCon(MeterHandle, long); 
long GetMRefCon(MeterHandle); 
/* Special meter functions */ 
void SetNeedleValue(MeterHandle, long); /* use this 
to move the needle */ 
long GetNeedleValue(MeterHandle); 
long GetDisplayDivisor(MeterHandle); 
Boolean ValidMeter (MeterHandle); 
int GetMaxTitlePixelsCMeterHandle); /* displayable 
title width */ 
void MeterSnapshot(MeterHandle); /* draws meter 
to thePort rather than owning window */ 


/* support functions used in this file only */ 
void InitMeters(void); 

void CreateMeterBackground(MeterHandle); 
void DrawMeterBackground(MeterHandle); 

void DrawMeterTitleCMeterHandle); 

void  DrawTriengle(MeterHandle, int); 

void  DrawNeedleCMeterHandle); 

void DrawSet(MeterHandle); 

void ShowValue(MeterHandle, Boolean); 

void X DrawInactiveMeterCMeterHandle?); 
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Boolean visible; 
long meterValue, meterMin, meterMax; 
long neterRfCon; 


int i,j; 

MeterHandlemH, tempMH; 

MeterPtr mPtr; 

WindowPeek «Рк = CWindowPeek)wPtr; 
char *titlePtr; 


/* Initialize sine table if necessary. */ 

if (sineTable[45] == Ø) /* should be 707 */ 
InitMeters(); 

/* Allocate and attach a new meter record. */ 

mH = (MeterHandle )NewHandle(Csizeof (MeterRecord)); 

if (MemError() != noErr) 
return(NULL); 

mPtr = *mH; 

mPtr->meterOwner = wPtr; 

mPtr-»nextMeter = NULL; 

mPtr-»hasMeterID = HASMETER; 

/* refCon of WindowRecord holds first MeterHandle. New 
meters are inserted at beginning of list. */ 

tempMH = (MeterHandle)(CwPk->refCon); 

wPk-»refCon = Clong)mH; 

1f CtempMH && ((**tempMH).hasMeter ID == HASMETER)) 
mPtr->nextMeter = tempMH; 

/* Fill in the easy fields. */ 

mPtr->meterVis = visible; 

mPtr->meterHilite = 0; /* active */ 

/* meterMin <= meterValue <= meterMax */ 

1f (meterMax < meterMin) 


DisposeMeter (mH); 
return(NULL); 


1f (meterValue < meterMin) 
meterValue = meterMin; 
1f (meterValue > meterMax) 
meterValue = meterMax; 
1f (meterMin == meterMax) 
(**nH).meterHilite = 255; /*inactive-see IM 1-327 */ 
mPtr->meterValue = meterValue; 
mPtr-»meterMin = meterMin; 
mPtr->meterMax = meterMax; 
mPtr->meterRfCon = meterRfCon; 
mPtr->needleValue = meterMin; /* default value */ 
j = title(0]; 
if (j> 31) 
j = 31; 
titlePtr = mPtr->title; 
for (i = 0; i <= j; ++i) 
*titlePtr++ = *titlett+; 
(**mH).meterRect = *boundRect; 
(**mH).halfSetWidth = HALFSETWIDTH; 
/* Do the grunt work. */ 
CreateMeterBackground(CmH); 
/* Drew meter if visible. */ 
if (visible) 


(**mH).meterVis = FALSE; /* forces drawing */ 
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e m; 


return(mH); 
) /* end NewMeter() */ 


void DisposeMeter(mH) 
i id mH; 


Rect tempRect; 
PicHandle tempPH; 
PolyHandle tempPoly; 
Me terHand1e tMH; 
GrafPtr savePort; 


if (!ValidMeter(mH)) return; 
GetPort(&savePort); 
SetPortCC**mH) .meterOwner); 
tempPH = (**mH).backgroundH; 
KillPictureCtempPH); 

tempPoly = (**mH). incUpH; 
Kil1PolyCtempPoly); 

tempPoly = (**mH). incDownH; 
KillPolyCtempPoly2; 

tempPoly = (**mH).pageUpH; 
KillPolyCtempPoly); 

tempPoly = (**mH).pageDownH; 
KillPolyCtempPoly); 

tempRect = (**mH).meterRect; 
EraseRect(&tempRect); 
InvalRect(&tempRect ); 

/* Unlink the meter. */ 

{МН = (MeterHandle) 
CCCWindowPeek ((**mH).meterOwner ))->refCon); 
if (tMH != mH) 


( 
while ((**tMH).nextMeter != mH) 

{МН = (**tMH).nextMeter; 
(**tMH).nextMeter = (**mH).nextMeter; 


else 
CCWindowPeek )((**mH).meterOwner ))->refCon = 
Clong)(C*#*mH) .nextMeter 2; 
DisposHandleCCHandle2mH); 
SetPort(CsavePort); 
) /* end DisposeMeter() */ 


void KillMetersCwPtr) 
WindowPtr wPtr; 


WindowPeek wPk = (WindowPeekOwPtr; 


while CwPk->refCon && ((**((MeterHandle) 
CwPk~»refCon))).hasMeterID == HASMETER)) 
DisposeMe ter ( (Me terHandle)CwPk->refCon)); 
) /* end KillMeters() */ 


void SetMTitle(mH, title) 

MeterHandle mH; 

ib *title; 
int j, i = titlel@); 
GrafPtr savePort; 
Rect tempRect; 


if (!ValidMeter(mH)) return; 
if Ci > 3D 

i = 31; 
if CD 

( 


for (j = 0; j <= i; ++j) 
(**mH).title[j] = title[j); 
GetPort(&savePort); 
SetPort((**mH).meterOwner); 
DrawMeterTitle(mH); 
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SetPort(savePort); 
) /* end SetMTitle() */ 


void GetMTitle(mH, title) 
MeterHandle mH; 
char *title; 


int j, i = (**mH).title(01]; 


if (!ValidMeter(mH)) 


title[0] = 0; 
return; 


for (j = 0; j «i; ++j) 
title[j] = (**mH). titlelj]; 
) /* end GetMTitle() */ 


void HideMeter (mH) 
MeterHandle mH; 


Rect tempRect; 
GrafPtr savePort; 


if C!ValidMeter(mH)) return; 


if (!(**mH).meterVis) return; 


GetPort(&savePort); 
SetPortCC**mH) .meterOwner ); 
(**mH).meterVis = FALSE; 
tempRect = (**mH).meterRect; 
EraseRect(&tempRect); 
InvalRect(&tempRect); 
SetPort(savePort); 

) /* end HideMeter() */ 


void ShowMeter(mH) 
MeterHandle mH; 


int 1; 
GrafPtr savePort; 


if (!ValidMeter(mH)) return; 
if ((**mH).meterVis) return; 
GetPort(&savePort); 
SetPortCC**mH) .meterOwner); 
(**mH).meterVis = TRUE; 
DrawMeterBackground(mH); 


for (i = inUpButton; i <= inPageDown; 


DrewIriengleCmH, i); 
DrawNeedle(mH); 
DrawSet (mH); 
ShowValue(mH, TRUE); 
SetPort(savePort); 
) /* end ShowMeter() */ 


void  DrawMeters(CwPtr) 
WindowPtr wPtr; 
( 


int i; 
GrafPtr savePort; 


MeterHandlemH = (MeterHandle)(CCWindowPeek dwPtr )->refCon); 


if (!ValidMeter(mH)) return; 
GetPor t(&savePort); 
SetPortCwPtr); 

while (mH) 


{ 
і? ((**mH).meterVis) 


DrawMeterBackground(mH); 


for (i = inUpButton; i<=inPageDown; ++i) 


DrawTriangleCmH, i); 
DrawNeedleCmH); 
DrawSetCmH); 


195 


ShowValue(mH, TRUE); cid &CC**mH) .meterRect?2) 


mH = (**mH).nextMeter; foundIt = TRUE; 
) break; 
SetPort(savePort); 
) /* end DrawMeters() */ mH = (**mH).nextMeter; 
void HiliteMeter(mH, hiliteState) if (foundIt && CpartCode = TestMeter(mH, thePoint))) 
MeterHandle mH; 
int hiliteState; *mHP = mH; 
( return(partCode); 
int i 
GrafPtr savePort; *mHP = NULL; 
return(C0); 
if (!ValidMeter(mH)) return; ) /* end FindMeter() */ 
1f (C**mH).meterHilite == hiliteState) return; 
if ((**mH).meterHilite == 255 && hiliteState != 0)return; /* See ThumbControlC) in MeterMain.c for an inside look at 
GetPor t(&savePort); tracking a moving indicator. */ 
SetPor t((**mH).meterOwner ); int TrackMeter(mH, startPoint, actionProc) 
1f CinUpButton <= hiliteState && MeterHandle mH; 
hiliteState <= inPageDown) Point star tPoint; 
voidPtr actionProc; 
(*¥mH) .meterHilite = hiliteState; 
DrawTriangle(mH, hiliteState); int par tCode; 
Point theMouse; 
else if (hiliteState == inBackground) Rect partRect, slopRect; 
( /* see "define at top of file */ Boolean pausing = FALSE; 
(**mH).meterHilite = hiliteState; 
ShowValueCmH, FALSE); partCode = TestMeter(mH, startPoint); 
) if C!partCode) return(0); 
else if ChiliteState == 0) /* make normal */ if CinUpButton <= partCode && 


partCode <= inPageDown) 


1f (C**mH).meterHilite == 255) 
( /* Hilite part & call actionProc while mouse down in part. */ 


(**mH).meterHilite = Ø; if (partCode == inUpButton) 
DrawMeterBackground(mH); partRect = (**mH).incUpRect; 
for Ci = inUpButton; i<=inPageDown; ++i) else if (partCode == inDownButton) 
DrawTriangleCmH, 1); partRect = (**mH). incDownRect; 
DrawNeedle(mH); else if (partCode == inPageUp) 
DrawSet(mH); partRect = (**mH).pageUpRect; 
ShowValueCmH, TRUE); else if (рагіСоде == inPageDown) 
partRect = (**mH).pageDownRect; 
else if CinUpButton <= (**mH).meterHilite && slopRect = partRect; 
(**mH).meterHilite <= inPageDown) InsetRect(&slopRect, -10, -10); 
( HiliteMeter(mH, partCode); 
hiliteState = (**mH).meterHilite; while (Stil 1Down()) 
(**mH).meterHilite = 0; ( 
DrawTriangle(mH, hiliteState); GetMouseC&theMouse); 


1f (PtInRectCtheMouse, &slopRect)) 
else if ((**mH).meterHilite == inBackground) ( 
if (pausing) 
(¥*mH) .meterHilite = Ø; ( 


ShowValue(mH, TRUE); pausing = FALSE; 
) амды. par tCode); 


) 
else if ChiliteState == 255) /*make inactive*/ if CactionProc) 
( (*actionProc)(mH, partCode); 
(**gH).meterHilite = hiliteState; 
DrawMeterBackground(mH); ira 
SetPort(savePort); if (!pausing) 
) /* end HiliteMeter() */ ( 


pausing = TRUE; 


int FindMeterCthePoint, wPtr, mHP) HiliteMeter(mH, 0); 
Point thePoint; ) 
WindowPtr wPtr; ) 
MeterHandle  *mHP; ) 
( if C!pausing) 
int partCode; HiliteMeter(mH, 2); 
Boolean foundIt = FALSE; 
MeterHandlemH = (MeterHandle)(( CWindowPeek )wP tr )->refCon); else if (partCode == inBackground) 
(/* see "define at top of listing */ 
while (ValidMeter(mH)) ShowValue(mH, FALSE); 
( while (StillDown()) 
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1f CactionProc) 
(*actionProc)(); 


) 
Spon Qa TRUE); 


else return(2); 
) /* end TrackMeter() */ 


int TestMeter(mH, thePoint) 
MeterHandle mH; 
i thePoint; 

int par tCode; 


if (!ValidMeter(mH)) return(d); 
ғы &((**mnH).meterRect))) 


М && ((**mH).meterHilite != 255)) 


if (PtInRectCthePoint, &((**mH).incUpRect))) 
partCode = inUpButton; 

else if (PtInRectCthePoint,&CC**mH). incDownRect))) 
partCode = inDownButton; 

else if (PtInRect(thePoint, &((**mH).pageUpRect))) 
partCode = inPageUp; 

else if(PtInRect(thePoint, &CC**mH) .pageDownRect 22) 
partCode = inPageDown; 


else 
partCode = inBackground; 
return(partCode); 
) 
return(0); 


) /* end TestMeter() */ 


void MoveMeter(mH, h, v) 


MeterHandle mH; 
int h,v; 


Boolean 


wasVisible = (**mH).meterVis; 


if (!ValidMeterCmH)) return; 


і? (wasVisible) 
HideMeter (mH); 
OffsetRectC&CC**mH). 
OffsetRectC&CC**mH). 
OffsetRectC&CCEXmH). 
OffsetRect(%&((**mH). 
OffsetRect(&((**mH). 
OffsetRect(&((**mH). 
(**mH).dialCentre.h 
(**mH).dialCentre.v 
1f (wasVisible) 

ShowMeter(mH); 


meterRect), h, v); 
incDownRect), h, v); 
incUpRect), h, v); 
pageDownRect), h, v); 
pageUpRect), h, v); 
displauRect), h, v); 
+= h; 

= у]. 


) /* end MoveMeter() */ 


void DragMeter(mH, startPoint, limitRect, slopRect, 


MeterHandle mH; 


Point startPoint; 
Rect x]imitRect; 
Rect *slopRect; 
int axis; 


long posOffset; 
int h,v; 


Rect mRect, tRect; 


GrafPtr 
RgnHandle  tempRgn; 


savePort; 


if (!ValidMeter(mH)) return; 


GetPortC&sevePort); 


SetPortCC**mH).meterOwner); 


tempRgn = NewRgn(); 
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axis) 


mRect = (**mH).meterRect; 

mRect.bottom -= TITLEHEIGHT; 

tRect. left = (**mH).meterRect.left + 2; 
tRect.right = (**mH).meterRect.right - 2; 
tRect.bottom = (**mH).meterRect.bottom - 2; 
tRect.top = tRect.bottom - TITLEHEIGHT + 4; 


OpenRgn(); 
FrameRoundRectC&mRect , mRect .right/10,mRect.bottom/ 10); 
FrameRect(ktRect); 

CloseRgn(tempRgn); 


posOffset = DragGrauRgn(tempRgn,startPoint, 


limitRect,slopRect, axis,@L); 


DisposeRgn( tempRgn); 
v = HiWord(posOf fset); 
h = LoWord(posOf fset); 


1f (v != -32768 && h != -32768) 
MoveMeter(mH, h, v); 

SetPort(savePort); 

) /* end DragMeter() */ 


/* Meter proportions are fixed - width determines height. */ 


void SizeMeter(mH, w) 
MeterHandle mH; 


int w; 
( 
PicHandle tempPH; 
PolyHandle tempPoly; 
Boolean wasVisible = (**mH).meterVis; 


if (!ValidMeter(mH)) return; 
if CwasVisible) 

HideMeter (mH); 
/* gut the meter and recreate it */ 
tempPH = C**mH).backgroundH; 
KillPictureCtempPH); 
tempPoly = (**mH). incUpH; 
KillPolygCtempPoly); 
tempPoly = (**mH). incDownH; 
KillPolgCtempPoly2; 
tempPoly = (**mH).pageUpH; 
KillPolyCtempPoly2; 
tempPoly = (**mH).pageDownH; 
KillPolgCtempPoly?; 
(**mH).meterRect.right = (**mH).meterRect.left + w; 
CreateMeterBackground(mH); 
if (wasVisible) 

showMe ter (mH); 
) /* end SizeMeter() */ 


void SetMtrValue(mH, meterValue) 
MeterHandle mH; 
long meterValue; 
GrafPtr savePort; 
if (!ValidMeter(mH)) return; 
GetPor tC&savePor t ); 
SetPor tCC**mH) . meterOwner 2; 
DrawSet(mH); /* erases old pointer */ 
/* pin value to range min:max */ 
if (meterValue < (**mH).meterMin) 
meterValue = (**mH).meterMin; 
else if (neterValue > (**mH).meterMax) 
meterValue = (**mH).meterMax; 
(**mH).meterValue = meterValue; 
DrawSet(mH); 
ShowValue(mH, FALSE); 
SetPort(savePort); 
) /* end SetMtrValue() */ 


long GetMtrValueCmH) 
MeterHandle mH; 
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( 

1f (!ValidMeter(mH)) returnCOL); 
returnCC**mH) meter Value); 

) /* end GetMtrValue() */ 


void SetMtrMin(mH, minValue) 
MeterHandle mH; 
long minValue; 


GrafPtr savePort; 


if (!ValidMeter(mH)) return; 
GetPort(C&savePort?); 
SetPortCC**mH).meterOwner ); 
DrawSet(mH); /* erases old pointer */ 
DrawNeedle(mH); /* ditto needle */ 

if CminValue >= (**mH).meterMax) 


(**mH).meterMin = (**mH).meterMax; 


HiliteMeter(mH, 255); /* inactive - see IM 1-327 */ 


return; 
) 


(**mH).meterMin = minValue; 

1f (C**nH5.meterValue < minValue) 
(**mH).meterValue = minValue; 

SetDisplayDivisor(mH); 

DrawSet (mH); 

DrawNeedle(mH); 

ShowValueC(mH, FALSE); 

SetPort(savePort); 

) /* end SetMtrMin() */ 


long GetMtrMinCmH) 
MeterHandle mH; 


if (!ValidMeter(mH)) return(@L); 
return((**mH).meterMin); 
) /* end GetMtrMin() */ 


void SetMtrMax(mH, maxValue) 
MeterHandle mH; 
long maxValue; 


GrafPtr savePort; 


if C!ValidMeter(mH)) return; 
GetPort(&savePort?; 

SetPor tCC**mH). meterOwner ); 
DrawSet(mH); /* erases old pointer */ 
DrawNeedle(mH); /* ditto needle */ 

if (maxValue <= (**mH).meterMin) 


(**mH).meterMax = (**mH).meterMin; 


HiliteMeter(mH, 255); /* inactive - see IM 1-327 */ 


return; 
) 


(**mH).meterMax = maxValue; 

і? ((**mH).meterValue > maxValue) 
(**mH).meterValue = maxValue; 

setDisplayDivisor(mH); 

DrawSet(mH); 

DrawNeedle(mH); 

ShowValueCmH, FALSE); 

SsetPor tCsavePor t); 

) /* end SetMtrMax() */ 


MeterHandle mH; 
long refCon; 


( 

if (!ValidMeter(mH)) return; 
(**mH).meterRfCon = refCon; 
) /* end SetMRefCon() */ 


long GetMRefCon(mH) 
MeterHandle mH; 


if (!ValidMeter(mH)) returnCOL); 
returnCC**mH) .meterRf Con); 
) /* end GetMRefCon() */ 


void SetNeedleValue(mH, value) 
MeterHandle mH; 
long value; 


GrafPtr savePort; 


if (!ValidMeter(mH)) return; 
1# (C**mH).needleValue == value) return; 
GetPortC&savePort); 
SetPor t((**mH).meterOwner ); 
DrawNeedle(mH); /* erases old needle */ 
/* pin value to range min:max */ 
if (value < (**mH).meterMin) 
value = (**mH).meterMin; 
else if (value > (**mH).meterMax) 
value = (**mH).meterMax; 
(**mH).needleValue = value; 
DrawNeedleCmH); 
ShowValueCmH, TRUE); 
SetPort(savePort); 
) /* end SetNeedleValue() */ 


long GetNeedleValueCmH) 
ii baa mH; 


if (!ValidMeter CmH2) returnCOL); 
returnCC**mH) .needleValue); 
) /* end GetNeedleValue() */ 


long GetDisplayDivisor (mH) 
MeterHandle mH; 


if (!ValidMeter(mH)) return(OL); 
return((**mH).displayDivisor); 
) /* end GetDisplayDivisor() */ 


Boolean ValidMeter (mH) 
MeterHandle mH; 


( 

1f (mH && C**mH).hasMeterID == HASMETER) 
return(TRUE); 

return(FALSE); 

) /* end ValidMeter() */ 


int GetMaxTitlePixelsCmH) 
MeterHandle mH; 


( 

1f (!ValidMeter(mH)) returnC0); 

return((**mH).meterRect.right - 
(**mH).meterRect.left - 4); 

) /* end GetMaxTitlePixels() */ 


long GetMtrMaxCmH) /* А meter, like a scroll bar, is very attached to its owning 

MeterHandle mH; window. Only MeterSnapShotC) will allow you to draw a meter in 
( another grafPort. Set the port, and set the font in the port 
1f (!ValidMeter (mH?) returnC2L); to something appropriate for the meter title before call.*/ 
returnCC**mH) .meterMax2; void MeterSnapshot(mH) 
) /* end GetMtrMaxC) */ з mH; 

void SetMRefCon(mH, refCon) int i; 
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Byte mVis, mHilite; 


if (!ValidMeter (mH)? return; 
mVis = (**mH).meterVis; 
mHilite = (**mH).meterHilite; 
(**mH).meterVis = TRUE; 
(**mH).meterHilite = 0; 
DrawMeterBackground(mH); 
for (i = inUpButton; i <= inPageDown; ++i) 
Drawlriangle(mH, i); 
DrawNeedleCmH); 
DrawSet(mH); 
ShowValue(mH, TRUE); 
(**mH).meterVis = mVis; 
(**mH).meterHilite = mHilite; 
) /* end MeterSnapshot() */ 


/* Functions used onlu in this file from here on */ 


/* Load up a table of sines to avoid going off on a tangent 
(sorry). If this table were entered by hand, «math.h? would 
not be needed. */ 

void InitMeters() 


int i; 
double x; 


for (i = 0; i <= 90; ++i) 
( 


x = ((double)i*PI)/180.0; /* convert degrees to radians */ 
аи = (іп )СѕіпСх ) 1000.0); 


) /* end InitMeters() */ 


/* The real fun - create the meter background picture and set 
up points and rects needed for drawing it. We could also have 
created the background in a drafting program and just scale it 
to the meter’s rectangle, but this wouldn't be as precise or 
as easy to modify */ 

void CreateMeterBackground(mH) 

ыы mH; 


int i, j, k, h, v, posInc; 
1ong theSin, theCos; 
1ong radius, xo, uo, lowestTickH, lowestTickV; 
Rect boundRect, theClipRect, 
tempRect, innerCircle; 
GrafPtr savePort; 
RgnHandle clpRgn, dialRgn, innerTickRgn; 
PenStete — pState; 
PicHandle tempP icH; 
PolyHandle tempPoly; 
Point c, 1, r; /* centre, left, right of polygons */ 
GetPort(&savePort); 


SetPortCC**mH) .meterOwner); 

/* adjust meterRect - meter proportions are fixed, 
meterRect.bottom is ignored */ 

boundRect = (**mH).meterRect; 

if (boundRect.right - boundRect.left < MINWIDTH) 

boundRect.right = boundRect. left + MINWIDTH; 
boundRect.bottom = boundRect.top + CCboundRect.right - 
boundRect . lef t)*TVHRATIO)/ 1000; 

tempRect = boundRect; 

boundRect.bottom += TITLEHEIGHT; 

(**mH).meterRect = boundRect; 

/* first adjust the clip; */ 

clpRgn = NewRgn(); 

dialRgn = NewRgn(); 

innerTickRgn = NewRgn(); 

GetClipCclpRgn); 

/*draw meter in rectangle starting at 0,0 for convenience */ 

Of f setRect C&boundRect , -boundRect . lef t, -boundRect . top); 

OffsetRect(&tempRect,-tempRect.left, -tempRect. top); 
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theClipRect = boundRect; 
theClipRect.right += 100; 
theClipRect bottom += 200; 
ClipRect(&theClipRect); 
GetPenStateC&pState); 


tempPicH = OpenPicture(&boundRect); 
PenNormal(); 
/* draw black rounded rect */ 
FillRoundRect(&tempRect, tempRect .right/ 10, 
tempRect .right/18,black); 
і = tempRect bottom; 
/* and frame two white circles */ 
tempRect .bottom = tempRect.right; /*square it off */ 
InsetRect(&tempRect, tempRect.right/15, 
tempRect .right/ 15); 
j = tempRect бої (оп; 
FillovalC&tempRect, white); 
InsetRect(&tempRect, 3, 3); 
radius = CtempRect.right - tempRect. left)/2; 
(**mH).dialCentre.h = tempRect.left + radius; 
(**mH).dialCentre.v = tempRect.top + radius; 
FrameOvalC&tempRect); 
OpenRgn(); 
FrameOval(&tempRect); 
CloseRgn(dialRgn); 
k = radius - (radius*INNERPCT + 5012/1001; 
InsetRect(&tempRect, k, k); 
innerCircle = tempRect; 
OpenRgn(); 
FrameOval(C&tempRect?; 
CloseRgnC innerT ickRgn); 
DiffRgnCdialRgn, innerTickRgn, dialRgn); /* That 
made a ring */ 
DisposeRgn( innerTickRgn); 
/* white out rect for control triangles */ 
tempRect.top = j + j/20; /* j = bottom of 
larger dial circle */ 
tempRect. left = (**mH).dialCentre.h - radius; 
tempRect bottom = i - j/28;/*i = bottom of rounded rect */ 
tempRect right = (**mH).dialCentre.h + radius; 
i = j = tempRect.right - tempRect. left; 
i = (1/42%4; 
tempRect.left += (j -i)/2; 
tempRect.right = tempRect.left + i; 
FillRect(&tempRect, white); 
/* Put lines between the control triangles. */ 
MoveToCtempRect.left + i/4, tempRect. top); 
(іле(0, tempRect.bottom - tempRect. top); 
Movelo(tempRect.left + i/2, tempRect.top); 
Line(6, tempRect.bottom - tempRect.top); 
MoveToCtempRect. left + 1/4 + 1/2, tempRect. top); 
Сіпесб, tempRect.bottom - tempRect. top); 
tempRect.right = tempRect. left + 1/4; 
(**mH).pageDownRect = tempRect; 
OffsetRect(&tempRect, 1/4, 0); 
(**mH).incDownRect = tempRect; 
OffsetRect(&tempRect, 1/4, 0); 
(**mH).incUpRect = tempRect; 
OffsetRect(&tempRect, 1/4, 0); 
(**mH).pageUpRect = tempRect; 
SetClipCdialRgn); 
/* dialRgn is the ring for the ticks */ 
PenSize(2,2); 
/* Draw the major ticks around circumference of dial */ 
h = (**mH).dialCentre.h; 
у = (**mH).dialCentre.v; 
1f CNUMTICKS >= 3) 
posInc = 2500 /СМОМТІСКЅ - 1); 
for (j = -1250; j <= 1250; 
j += posInc? 


i = j/18; 
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GetSinAndCosCi, &theSin, &theCos); 

хо = (radius*theSin + 500L2/1000L + h; 
yo = (-radius*theCos + 500L)/1000L + v; 
Movelo(h - 1, v - 1); 

LineTo(xo - 1, uo - 1); 


/* and now the minor ticks */ 
PenSize(1,1); 
1€ CNUMMINORTICKS >= 3) 


( 
posInc = 2500/(NUMMINORTICKS - 1); 
for (j = -1250; j <= 1250; 

j += posInc) 


i = j/10; 

/* determine sine and cosine to use */ 
GetSinAndCosCi, &theSin, &theCos); 
xo = (radius*theSin + 500L)/1000L + h; 
yo = (-radius*theCos + 500L)/1000L + v; 
Movelo(h - 1, v - 1); 
LineTo(xo - 1, yo - 1); 


) 


ClipRectC&theCl ipRect); 

DisposeRgn(dialRgn); 

/* White out centre - needed for clipboard copying.*/ 

Fill0valC&innerCircle, white); 

/* Put small black circle in centre of dial.*/ 

tempRect.top = (**mH).dialCentre.v - CENTRERADIUS; 

tempRect.left = (**mH).dialCentre.h - CENTRERADIUS; 

tempRect.bottom = (**mH).dialCentre.v *CENTRERADIUS; 

tempRect.right = (**mH).dialCentre.h + CENTRERADIUS; 

FillOvalC&tempRect, black); 

/* Set up and draw displayRect just below dial centre. */ 

lowestTickH = C(xo - hO*INNERPCT2/100L + h; 

lowestTickV = ((у0 - v)*INNERPCT)/100L + v; 

tempRect.right = lowestTickH -2160/CC**mH).meterRect .right 
- (**mH).meterRect . lef t); 

tempRect.left - tempRect.right - 2*CtempRect.right - h2; 

tempRect.top = Cint)lowestTickV; 

tempRect.bottom = tempRect.top + 16; 

(**mH).displayRect = tempRect; 

AdjustDisplay(mH); 

tempRect = (**mH).displayRect; 

OffsetRect(&tempRect, -1, 0); 

FrameRectC&tempRect); 

MoveToCtempRect.left + 1, tempRect.bottom); 

LineToCtempRect.right, tempRect .bottom); 

MoveToCtempRect.right, tempRect.top + 1); 

LineToCtempRect.right, tempRect. bottom); 

InsetRect(&tempRect, 1, 1); 

i = (*¥mH).meterRect. left; 

j = (**mH).meterRect. top; 

OffsetRect(&tempRect, i,j); 

C¥*¥mH) .displayRect = tempRect; 

SetDisplayDivisor (mH); 

ClosePicture( ); 


(**mH).backgroundH = tempPicH; 
/* Define up and down arrows as triangular polygons.*/ 
/* page up poly */ 
tempRect = (**mH).pageUpRect; 
].h = tempRect. left + CtempRect.right - 
tempRect . lef 2/8; 

= tempRect.right - CtempRect.right 

- tempRect.left)/8; 
r.h - l.h; /* side length of triangle */ 
(1/2)*2; 
= ].h + i; 
Ci*PGPOLYHEIGHT + 1000)/2000; /* vertical 

height, 1/2side * root3 */ 

c.v = tempRect.top + (tempRect.bottom - tempRect.top - j)/2; 


=> 


r. 


Qu. y —- —.- 
"zu 


c.h = tempRect.left + CtempRect.right - tempRect.left)/2; 
lv = с.у + j; 

Гу = С.у + j; 

{ 


empPolu = OpenPolu(); 
Movelo(c.h, c.v); 
LineToCl.h, 1.v); 
LineTo(r.h, r.v); 
LineTo(c.h, c.v); 
ClosePoly(); 
(**mH).pageUpH = tempPoly; 
/* inc up poly */ 
tempRect = (**mH). incUpRect; 
1.ћ = tempRect.left + CtempRect.right - tempRect. lef t2/4; 


r.h = tempRect.right - CtempRect.right - tempRect.left)/4; 
i 7 r.h - l.h; /* side length of triangle */ 
i = (1/20*2; 
r.h = 1.h t i; 
j = Ci*INCPOLYHEIGHT + 1000)/2000; /* vertical 
height, 1/2side * root3 */ 
с.у = tempRect.top + (tempRect.bottom - tempRect.top - j)/2; 
c.h = tempRect.left + (tempRect.right - tempRect.left)/2; 
1.у = c.v + j; 
r.v = c.v + j; 
tempPoly = OpenPolu(); 


Movelo(c.h, c.v); 
LineToCl.h, 1.v); 
LineTo(r.h, r.v); 
Linelo(c.h, c.v); 

ClosePolu(); 

(**mH).incUpH = tempPolu; 

/* inc down poly */ 

tempRect = (**mH). incDownRect; 


1.һ = tempRect.left + CtempRect.right - tempRect.left)/4; 
r.h = tempRect.right - CtempRect.right - tempRect.left)/4; 
i 7 r.h - l.h; /* side length of triangle */ 
1 = (1/2)*2, 
r.h = ].h + i; 
j = Ci*INCPOLYHEIGHT + 10002/2000: /* vertical 
height, 1/2side * root3 */ 

с.у = tempRect.top + (tempRect.bottom 

- tempRect.top - j)/2 + j; 
c.h = tempRect.left + CtempRect.right - tempRect.left)/2; 
1.v = c.v - j; 
r.v = c.v - j; 
tempPoly = OpenPolu(); 


Movelo(c.h, c.v); 

LineToCl.h, 1.v); 

LineTo(r.h, r.v); 

LineToCc.h, c.v); 
ClosePoly(); 
(**mH). incDownH = tempPoly; 
/* page down poly */ 
tempRect = (**mH).pageDownRect; 
].h = tempRect. left + CtempRect.right - tempRect.left)/8; 
r tempRect.right - CtempRect.right - tempRect.left)/8; 
r.h - 1.h; /* side length of triangle */ 
С1/2)%2; 
= 1.h + i; 
Ci*PGPOLYHEIGHT + 10002 /2000; /* vertical 

height, 1/2side * root3 */ 


> 


"лә" 


i 
i 
P. 
J 


c.v = tempRect.top + (tempRect.bottom 
- tempRect.top - j)/2 + j; 
c.h = tempRect.left + CtempRect.right 


- tempRect.1left)/2; 
l.v = c.v - j; 
r.v = c.v - j; 
tempPolu = OpenPoly(); 
MoveToCc.h, c.v); 
LineToCl.h, 1.м); 
LineTo(r.h, r.v); 
LineToCc.h, c.v); 
ClosePoly(); 
(**mH).pageDownH = tempPoly; 
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/* Set up needle and set point parameters. */ 

radius = (radius*(INNERPCT-2L) + 50L)/100; 
(**mH).needleLong = radius; 

(**mH).setLong = radius; 

(**mH).needleShort = ClowestTickV - (**mH).d.alCentre.v)/2; 
(**mH).setShort = (**mH).needleShort; 
(**mH).halfNeedleWidth = radius/HALFNEEDLERATIO; 


/* Move rects and points to proper position. */ 
i = (**mH).meterRect . left; 

j = (**mHD.meterRect. top; 

Of fsetRect(&CC**mH). incDownRect), i,j); 
Of fsetRect(&CC**mH). incUpRect), i,j); 

Of FfsetRect(&CC**mH).pageDownRect), i,j); 
Of fsetRect(&CC**mH).pageUpRect), i,j); 
(**mH).dialCentre.h += i; 
(**mH).dialCentre.v += j; 

/* clean up on the wau out */ 
SetPenState(&pState); 

SetClipCclpRgn); 

DisposeRgnCclpRgn); 

SetPort(savePort); 

) /* end CreateMeterBackground() */ 


void DrawMeterBackground(mH) 
MeterHandle mH; 


( 

PicHandle tempPH = (**mH5.backgroundH; 
Rect tempRect; 

PenState pState; 


GetPenStateC&pState); 
PenNormal(); 

tempRect = (**mH).meterRect; 
EraseRect(&tempRect); 

if (C**mH).meterVis) 


( 
if ((**mH).meterHilite != 255) 
DrawPicture(tempPH, &tempRect); 
else 
DrawInactiveMeter(mH); 
DrawMeterTitleCmH); 


setPenStateC&pState); 
) /* end DrawMeterBackground() */ 


/* Title is centered and truncated if necessary, in whatever 
font is current. Drawing is clipped to the intersection of the 
title rect and the current clip region. */ 

void DrawMeterTitle(mH) 

Ë Gua. mH; 


int i,j, height; 
Rect tempRect; 
char title[32]; 


FontInfo tempInfo; 
PenState pState; 


RgnHandle oldClipRgn, titleClipRgn; 
ControlHandle cHH, cHV; 
char *mTPtr = (**mH).title; 


GetFontInfoC&tempInfo); 
height = tempInfo.ascent + tempInfo.descent 
+ tempInfo. leading; 

/* Copy title - text can’t be referenced by 

an unlocked handle when calling DrawString(). */ 
for (i20; i < 31; ++i) 

title[i] = mTPtr(il; 

/* Draw shadowed title box, effective height = 

TITLEHEIGHT-4, just below black rounded rect*/ 
tempRect.left = (**mH).meterRect.left + 2; 
tempRect right = (**mH).meterRect.right - 2; 
tempRect.bottom = (**mH).meterRect bottom - 2; 
tempRect.top = tempRect.bottom - TITLEHEIGHT + 4; 
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FrameRect(&tempRect); 

MoveToCtempRect. left + 1, tempRect bottom); 
LineToCtempRect.right, tempRect.bottom); 
MoveToCtempRect.right, tempRect.top + 1); 
LineToCtempRect.right, tempRect.bottom); 

i = StringWidthCtitle); 

jJ = tempRect.right - tempRect. left; 

if (Cj - i) < 2) /* title too long - truncate */ 


while (StringWidth(title) > j - 2) 
title[0] -= 1; 
i = StringWidth(title); 


) 
GetFontInfo(&tempInfo); 
height = tempInfo.ascent + tempInfo.descent 
+ tempInfo. leading; 
MoveToCtempRect.left + (j - 12/2, tempRect.top + 
CtempRect bottom - tempRect.top)/2 - height/2 
+ tempInfo.ascent); 
oldClipRgn = NewRgn(); 
titleClipRgn = NewRgn(); 
GetClipColdClipRgn); 
RectRgn(titleClipRgn, &tempRect); 
SectRgnCtitleClipRgn, oldClipRgn, titleClipRgn); 
SetClipCtitleClipRgn); 
GetPenStateC&pState); 
PenNormal(); 


DrawString(title); 


SetPenState(&pState); 
SetClipColdClipRgn); 
DisposeRgnColdClipRgn?; 
DisposeRgn(titleClipRgn); 

) /* end DrawMeterTitle() */ 


/* The four triengles (two small, two large) 
correspond to the inc and page parts of a scroll bar. */ 


void  DrawIriangle(mH, partCode) 
MeterHandle mH; 
int par tCode; 


( 
PenState — pState; 
PolgHandle tempPoly; 


if (C**mH).meterHilite == 255) return; 

if CpartCode == inUpButton) 
tempPoly = (**mH). incUpH; 

else if (partCode == inDownButton) 
tempPoly = (**mH). incDownH; 

else if (partCode == inPageUp) 
tempPoly = (**mH).pageUpH; 

else if (partCode -- inPageDown) 
tempPoly = (**mH).pageDownH; 

else 
return; 

GetPenState(&pState); 

PenNormal(); 

OffsetPolyCtempPoly, (**mH).meterRect. left, 

(**mH) .meterRect . top); 
if (partCode == (**mH).meterHilite) 


OffsetPolgCtempPoly, -1, -1); 
il d black); 


else 
(/* neat way to shadow ANY polygon */ 
FillPolyCtempPoly, black); 
FramePolyCtempPoly); 
OffsetPolyCtempPoly, -1, -1); 
ErasePoly(tempPoly); 
nae ema 
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OffsetPolu(tempPolu, -(**mH).meterRect.left + 1, 
-(**mH).meterRect.top + i); 

SetPenState(&pState); 

) /* end DrawTriangle() */ 


void DrawNeedle(mH) 
MeterHandle mH; 


long 11, 12, 13, xa, xb, xc, xd; 
long theSin, theCos, ya, ub, uc, ud; 
int position; 

int h = (**mH).dialCentre.h; 

int у = (**mH).dialCentre.v; 
PenStete pState; 


PolyHandle needlePolu; 


1f C!CC(**mH).meterVis) || 
(**mH).meterHilite == 255) return; 

GetPenState(&pState); 

PenMode(patXor); 

PenPat(black); 

PenSize(1,1); 


/* Determine position of needle based onvalue. Position 
is the angle in degrees measured from 0 = straight up, 
increasing clockwise, range -125:*125 */ 
position = (((**mH).needleValue 

~ (**gH).meterMin2*250L) 

/CC**mH).meterMax - (**mH).meterMin) - 125L; 
if (position < -125) 

position = -125; 
1f (position > 125) 

position = 125; 
/* Determine sine and cosine to use. */ 
GetSinAndCosCposition, &theSin, &theCos); 
/* Calculate four vertices of needle indicator by 
changing from polar to rectangular coord’s and then trans- 
lating over to dial centre. */ 
11 = (**mH).needleLong; 
12 = (**mH).needleShort; 


13 = (**mH).halfNeedleWidth; 

ха = (-12*theSin + 5001 )/10001 + h; 
ya = (12*theCos + 500L)/1000L + v; 

xb = (11*theSin + 500L)/1000L + h; 

yb = (-11*theCos + 500L)/1000L + v; 
xc = (-13*theCos + 500L)/1000L + h; 
yc = (-13¥theSin + 500L)/1000L + v; 
xd = -xc + 2*h; 

yd = -yc + 2*v; 


needlePoly = OpenPolyC); 
MoveTo(xa, ya); 
LineTo(xc, uc); 
LineTo(xb, yb); 
LineTo(xd, ud); 
LineTo(xa, ya); 
ClosePoly(); 
PaintPoly(needlePoly); 
KillPolyCneedlePoly); 


SetPenState(&pState); 
) /* end DrawNeedle() */ 


void DrawSet(mH) 
MeterHandle mH; 


long 11, 12, 13, xe, xb; 
long theSin, theCos, ya, ub; 


int position; 

int thePenSize = (**mH).halfSetWidth*2; 
int h = (**mH).dialCentre.h; 

int v = (**mH).dialCentre.v; 


PenState pState; 
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if C!CC**mH).meterVis) || 
(**mH).meterHilite == 255) return; 

GetPenState(&pState); 

PenMode(patXor); 

PenPat(black); 

PenSize( thePenSize, thePenS ize); 


/* Determine position of set indicator from value. */ 
position = CCC**mH).meterValue -(**mH).meterMin)*250L) 
/CC**mH) .meterMax - C**mH).meterMin) - 1251; 
1f (position < -125) 
position = -125; 
if (position › 125) 
position = 125; 


/* Determine sine and cosine to use */ 
GetSinAndCos(position, &theSin, &theCos); 


/*Calculate two vertices of position indicator*/ 
11 = (**mH).setLong; 


12 = (**mH).setShort; 

13 = (**mH).halfSetWidth; 

ха = (-12*theSin + 500L)/1000L - HALFSETWIDTH + h; 
ya = (12*theCos + 500L)/1000L - HALFSETWIDTH + v; 

xb = (11*theSin + 5001 )/10001 - HALFSETWIDTH + h; 

yb = (-li*theCos + 500L)/1000L - HALFSETWIDTH + v; 


Movelo(xa, ya); 
LineToCxb, yb); 


SetPenState(&pState); 
) /* end DrawSet() */ 


void ShowValue(mH, needle) 
MeterHandle mH; 


Boolean needle; 
int 1 
int oldFont, oldSize; 


Style oldStyle; 

PenState pState; 

Tong theValue; 

Rect tempRect; 

char pNumStr[16]; /* pascal */ 


if (!((**mH).meterVis) || 
(**mH).meterHilite == 255) return; 
GetPenState(&pState); 
PenNormal(); 
oldFont = thePort->txFont; 
oldSize = thePort-»txSize; 
oldStyle = thePort-> txFace; 
TextFontCgeneva); 
TextSize( 12); 
TextFace(’ '); 
1f (needle) 
theValue = (**mH).needleValue; 
else 
theValue = (**mH).meterValue; 
/* Truncate value to fit display box. */ 
if (C**mH) displayDivisor > 1) 
theValue /- (**mH).displagDivisor; 
tempRect = (**mH).displayRect; 
NumToStringCtheValue, pNumStr); 
i = StringWidthCpNumStr); 
EraseRect(&tempRect); 
MoveToCtempRect right - i- 4, tempRect.top + 
(tempRect.bottom - tempRect.top)/2 + TEXTVOFFSET); 
DrawString(pNumStr); 
TextFontColdFont); 
TextSizeColdSize); 
TextFaceColdStyle); 
SetPenStateC&pState); 
) /* end ShowValue() */ 
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void DrawInactiveMeter (mH) 
MeterHandle mH; 


Rect tempRect; 


tempRect = (**mH).meterRect; 

tempRect.bottom -= TITLEHEIGHT; 

FrameRoundRect(&tempRect, tempRect .r ight/10, 
tempRect .bottom/ 10); 

) /* end DrawInactiveMeter() */ 


/* Ensure that digital display shows at least MINDIGITS and at 
most MAXDIGITS plus sign - called only during creation of 
background meter picture. */ 

void AdjustDisplay(mH) 

MeterHandle mH; 


int | oldFont, oldSize; 
Style oldStyle; 
int displayWidth = 
(**mH).displauRect.right 
- (**mH).displauRect.left; 
int minusW, num4W; 
int numDisplauDigits, wantedWidth, halfWidthDiff; 


oldFont = thePort->txFont; 

oldSize = thePort->txSize; 

oldStyle = thePort-> txFace; 

TextFont (geneva); 

TextSize( 12); 

TextFaceC' “); 

minusW = CharWidth(’-7); 

num4W = CharWidth(‘'4/); 

numDisplagDigits = (displayWidth - minusW - 8)/num4W; 
if CnumDisplayDigits < MINDIGITS)/*too small*/ 


wantedWidth = 8 + minusW + num4W*MINDIGITS; 
halfWidthDiff = (wantedWidth - displayWidth + 1)/2; 
(**mH) .displayRect. left -= halfWidthDiff; 

(**mH) .displayRect.right += halfWidthDiff; 


us if CnumDisplayDigits > MAXDIGITS) /* too big */ 


wantedWidth = 8 + minusW + num4W*MAXDIGITS; 
halfWidthDiff = (displayWidth - wantedWidth -12/2; 
(**mH).displayRect.left += halfWidthDiff; 
(**mH).displagRect.right -= halfWidthDiff; 


) 
TextFontColdFont); 
TextSizeColdSize); 
TextFaceColdStyle); 
) /* end AdjustDisplay() */ 


/* Set displayDivisor to appropriate power of ten so that as 
many digits as possible are shown in the display. Called when 
creating meter and also when setting meter max or min */ 

void SetDisplayDivisor (mH) 

MeterHandle mH; 


int — oldFont, oldSize; 

Style oldStyle; 

int displayWidth = (**mH).displayRect.right 
- (**nH).displayRect. left + 2; 

int  minusW, num4W, numDisplayDigits, 

wantToDisplay, power; 
long absMin, absMax; 
. char pNumStr(16); /* pascal */ 


oldFont = thePort-?txFont; 
oldSize = thePort-> txSize; 
oldStyle = thePort->txFace; 
TextFont (geneva); 

TextSize( 12); 
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TextFace(’ '); 
minusW = CharWidth(‘-/); 
num4W = CharWidthC'4"); 
numDisplayDigits = CdisplayWidth - minusW - 8)/num4W; 
absMin = ((**mH).meterMin < 2) ? 
- (*¥mH).meterMin : (**mH).meterMin; 
absMax = ((**mH).meterMax < 0) ? 
- (**mH).meterMax : (**mH).meterMax; 
if CabsMin > absMax) 
absMax = absMin; 
NumloString(absMax, pNumStr); 
wantToDisplay = (Cint)(pNumStr[(0]); 
if CwantToDisplay > numDisplayDigits) /* too many, 
must scale value down */ 


/* divisor = 10 raised to power 
(wantToDisplau - numDisplayDigits) */ 
power = wantToDisplay - numDisplauDigits; 

(**mH).displagDivisor = 101; 
while (-power › 0) 
(**mH) .displayDivisor *= 101: 


else /* no scaling necessary */ 
(**mH).displagDivisor = IL; 

TextFontColdFont); 

TextSizeColdSize); 

TextFaceColdStyle); 

) /* end SetDisplayDivisor() */ 


/* Position is interpreted as en engle in degrees. The values 
are retrieved from sineTeble[], which is an array of integers 
recording sines from 0 to 98 degrees, scaledup by 1000. Note 
zero degrees is straight up, & angles increase clockwise. */ 
void GetSinAndCos(position, theSin, theCos) 

int position; 

long *theSin, *theCos; 


( 
a a « -125 || position > 125) 
xtheSin 


xtheCos = 
return; 


ДЕ 
ДЕ 


) 
us if (-125 <= position && position <= -90) 


*theSin = -sineTable(position + 1801; 
*theCos = -sineTable[-position - 901; 


ur if (-90 < position && position <= 0) 


*theSin 
*theCos 


-sineTable[-position]; 
sineTable([position + 90]; 


) 
ra if (Ø < position && position <= 90) 


*theSin = sineTable[position]; 
*theCos = sineTable[98 - position]; 


bs /* 90:125 */ 


*theSin = sineTable[ 180 - position]; 
*theCos = -sineTable[position - 901; 


) 
) /* end GetSinAndCos() */ 
Listing: MeterMain.C 


/* MeterMain.c - test rig for designing meters, illustrating 
the interaction between documents, windows, and controls 
by Ken Earle, 1989 
ThinkC 3.0 settings: 
Options...; «MacHeaders?, Check Pointers, 
Require Protoypes 
Set Project Type...; File Type APPL, Creator whatever 
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Files: MacTraps 

Math 

Meter.c MeterMain.c 
Headers: «MacHeaders» <math.h> “Meter .h” 
Resources: none (What? Blasphemy!) 


*/ 

*include “Meter .h” 

"define APPLEID 15 

Sdefine  FILEID 16 

define EDITIO 17 

define QUIT 12 

define  HSCROLL IL /* scroll bar ID */ 
"define VSCROLL 2L 


Sdefine  SCROLLSIZE 15 

Sdefine ООСНЕІСНТ 720 /* 10" x 72 */ 

Sdefine DOCWIDTH 576 /*8" x 72 */ 

8Sdef ine MAXWINDOWWIDTH CDOCWIDTH + SCROLLSIZE) 

def ine MAXWINDOWHEIGHT CDOCHEIGHT + SCROLLSIZE) 

Sdefine — DISPLAYBOXWIDTH 72 /* <= Ø removes the display 
and disables DrawDisplayBox( )*/ 

/* display modes are used by DrawDisplayBox() */ 

iiu DisplayMode 


forWindow, forMeter, forThumb, forDebug = 300 
/* forces to 16-bit size */ 


); 
typedef enum DisplayMode DisplayMode; 


/* useful globals */ 

WindowRecord wRecordl, wRecord2; 
RgnHandle updateRgn; 

MenuHandle appleMenu, fileMenu, editMenu; 
/* hendy globals, bad style */ 

Rect dragRect = ( Ø, Ø, 1024, 1024); 
char wTitle1() = “\PRear Window”; 
char wlitle2[) = “\PFront Window”; 
char nTitle1(] = *\PFirst Meter’; 
char mTitle2(] = “\PSecond Meter’; 
char mTitle3[] = “\PThird Meter’; 
char mTitle4[] = “\PFourth Meter’; 


/*Prototypes for functions defined in this file*/ 

int main(void); 

void DoStandardInits(void); 

void MakeMenus(void); 

Boolean DoMenu( long); 

void MakeTwoWindows(void); 

void  MakeTwoMeters(WindowPtr, int); 

void DitherMeters(void); 

void DoContentCWindowPtr, EventRecord*); 

void | UpdateContents(WindowPtr, Boolean); 

void  DrawDisplayBox(WindowPtr, void**, 
DisplayMode, int, int); 

void  DoZoomWindow (WindowPtr, int); 

void | DoGrowWindowCEventRecord*); 

void DoCloseWindow(void); 

Boolean AMeterWindow(WindowPtr); 

void  GetScrollHandles(WindowPtr, ControlHandle*, Control- 

Handle*); 

void LocalToDoc(Point*); 

void MeterProc(MeterHandle, int); 

pascal void ScrollProcCControlHandle, int); 

void  ThumbControlCControlHandle, Point); 

void  PutMetersOnCl ipC(WindowPtr); 


Bainc) 

int part; 
EventRecord myEvent; 
WindowPtr whichWindow; 
GrafPtr savePort; 
MeterHandle mH; 
ControlHandle cH; 
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Rect cRect; /* see activateEvt */ 
RgnHandle tempRgn; /* see updateEvt */ 
Boolean quitting = FALSE; 
DoStandardInitsC); 

updateRgn = NewRgn(); 

MakeMenus(); 

Make TwoW indows( ); 


do /* while not quitting */ 


do /* while no next event */ 


SystemTask(); 

DitherMeters(); 

) whileC!GetNextEventCeveryEvent, &myEvent)); 
“| tch (muEvent.what) 


case mouseDown: 
“| tch (part = FindWindow(muEvent.where, &whichWindow)) 


case inDesk: 
SusBeep(2); 
break; 
case inMenuBar': 
quitting = 
DoMenu(MenuSelect(muEvent.where)); 
case inSusWindow: 
SustemClick(&muEvent,whichWindow); 
break; 
case inDrag: 
if (AMeterWindow(whichWindow)) 
DragWindow(whichWindow, myEvent.where, &dragRect); 
break; 
case inZoomIn: 
case inZoomOut : 
1f (AMeterWindow(whichWindow2) 
if (TrackBoxCwhichWindow, myEvent.where, part?) 
DoZoomWindowCwhichWindow, part); 
break; 
case inGrow: 
1f CAMeterWindowCwhichWindow)) 
DoGrowWindowC&myEvent); 
break; 
case inGoAway: 
1f CAMeterWindowCwhichWindow)) 
if (TrackGoAwayCwhichWindow, myEvent.where)) 
DoCloseWindowC); 
break; 


case inContent: 
1f (whichWindow != FrontWindowC2) 
Se lectWindowCwhichWindow); 
else 
if CAMeterWindow(CwhichWindow)) 
DoContent(whichWindow, &myEvent); 
break; 
default: 
break; 
) /* switch FindWindow */ 
break; 
case keyDown: 
case autokey: 
break; 
case activateEvt: 
whichWindow = CWindowPtr )myEvent .message; 
E MEE ыы ene 


mH =(MeterHandle )( (CW indowPeek )whichWindow)->refCon); 

cH = (CWindowPeek whichWindow)->controlList; 

M ens & activeF lag) 
SetPortCwhichWindow); 
ClipRect(&CwhichWindow->por tRect)); 
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InvalRect(&CwhichW indow-> por tRect)); whichWindow->portRect right, 


DrawGrowIcon(whichWindow); whichWindow- portRect .bottom); ; 
if (cH) DiffRgnCupdateRgn, tempRgn, updateRgn); 
( SetRectRgn(tempRgn, 
while (cH) whichWindow-> por tRect .right-SCROLLSIZE, 
{ whichWindow->portRect. top, 
ShowControl (cH); whichWindow->portRect.right, 
cRect = (**cH).contr]Rect; whichWindow->portRect .bottom-SCROLLSIZE); 
ValidRectC&cRect?; DiffRgnCupdateRgn, tempRgn, updateRgn); 
cH = (**cH).nextControl; DisposeRgn( tempRgn); 
) /* Redraw the "true contents" of the window. */ 
UpdateContentsCwhichWindow, 
if (ValidMeter(mH)) CwhichWindow == FrontWindow())); 
EndUpdateC whichWindow ); 
nos (mH) кшн 
/* activate meters */ break; 
(**mH).meterHilite = 0; default: 
mH = (**mH).nextMeter; break; 


) /* switch myEvent.what */ 


) ) while C!quitting); 
cRect = thePort-»portRect; if (FrontWindow()) 
cRect.bottom -= SCROLLSIZE; PutMetersOnC1 ipCFrontwWindow( )); 
cRect.right -= SCROLLSIZE; ) /* end main() */ 
ClipRect(&cRect); 
) /* if activate */ void  DoStandardInitsC) 
else 
( MoreMasters(); 
GetPortC&savePor t); MoreMasters(); 
SetPor tCwhichWindow); MoreMasters(); 
ClipRect(&CwhichWindow->portRect)); InitGraf (&thePort); 
InvalRect(&CwhichWindow-) por tRect)); InitFontsC); 
DrawGrowIconCwhichWindow); FlushEventsCevergEvent, 0); 
if (cH) InitWindows(); 
( InitMenus(); 
whi le(cH) TEInit(); 
InitDialogs(@L); 
HideControl(cH); InitCursor(); 
Y = (**cH).nextControl; )/* end DoStanderdInitsC) */ 
) void MakeMenus( ) 
1f (ValidMeter(mH)) 
appleMenu = NewMenuCAPPLEID, “\P\24"); 
while (mH) AppendMenuCappleMenu, *\PCAbout nothing. ..; (772; 
AddResMenuCappleMenu, ^DRVR'); 
/* deactivate meters */ InsertMenuCappleMenu, 2); 
C¥*¥mH).meterHilite = 255; 
mH = (**mH) .nextMeter ; fileMenu = NewMenu(FILEID, "VPF ile"); 
) AppendMenu(fileMenu,*VPNew;Open...;N 
) (-;Close;Save;Save as...;Revert;(-;N 
SetPort(savePort); Page Setup...;Print...;(-;Quit/Q”); 
) /* else deactivate */ InsertMenu(fileMenu,0); 
) /* if our window */ 
break; editMenu = NewMenu(EDITID,”\PEdit”); 
case updateEvt: AppendMenuCeditMenu, “\PUndo/Z; \ 
whichWindow = (WindowPtrOmyEvent .message; (-;Cut/X;Copy/C;Paste/V;Clear; (-;\ 
1f CAMeterWindowCwhichW indow)) Show Clipboard;Select A11”); 
( InsertMenuCeditMenu, ð); 
GetPor tC&savePor t ); 
SetPort( whichWindow ); DrawMenuBar О); 
ClipRect(&whichW indow->por tRect); ) /* end MakeMenus() */ 
BeginUpdateC whichWindow 2; 
EraseRectC&whichWindow-?portRect); /* DoMenu returns TRUE when quit selected */ 
DrawGrowIconCwhichWindow); Boolean DoMenuCmenuAndItem) 
DrawControlsCwhichWindow); long menuAndI tem; 
DrawDisplayBoxCwhichWindow, OL, forWindow, 0,0); 
/* Take the scrolls out of updateRgn, because int the! tem; 
UpdateContents() sets the clip region to the char пате [64], 
(global) updateRgn. */ 
CopyRgn(whichWindow-) visRgn, updateRgn ); theItem = LoWord(menuAnd! tem); 
tempRgn = NewRgn(); switch CHiWord(menuAnd! tem)) 
SetRectRgnCtempRgn, ( 
whichWindow->portRect. left, case APPLEID: 
whichWindow-) por tRect .bottom-SCROLLSIZE, if (theltem > 1) 
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( ( 
if (FrontWindow()) OffsetRect(kboundsRect, 10, 10); 


PutMetersOnClip(FrontWindow()); wPtr = NewWindow(&wRecord2, &boundsRect, 
GetItemCappleMenu, theltem, name); wlitle2, TRUE, 8,-1L,TRUE, 01); 
OpenDeskAcc(name); ) 

| SetPort(wPtr); 
break; ClipRect(&(thePort->portRect)); 
case FILEID: /* Adjust zoom rectangles since document size is fixed. */ 

if Ctheltem == QUIT) wsd = (WStateData*) *((CWindowPeek )wPtr )->dataHandle); 

returnCTRUE); wsd->stdState = boundsRect; 
break; wsd->userState = boundsRect; 
case EDITID: /* horizontal bar */ 
break; /* Note room is reserved at right of the bar for the 
default: displau box - see DrawDisplauBox(). */ 
break; cRect.top = thePort->portRect .bottom - SCROLLSIZE; 

) cRect.left = thePort->portRect.left - 1; 
HiliteMenu(0); cRect.bottom = thePort->portRect.bottom + 1; 
return(FALSE); cRect.right = thePort->portRect.right 
) /* end DoMenu() */ - DISPLAYBOXWIDTH - 14; 

cH = NewControlCthePort ,&сВесі, "P^, TRUE, 

/* Make two windows right off the bat, each with a couple of 0,0, horRange, scrollBarProc,HSCROLL); 
scroll bars and a couple of meters. The windows are sized to 14 ChorRange == 0) 
fit the screen, but limited HiliteControl(cH, 255); 
to a maximum size of 8" by 10" to show the slight complica- /* vertical bar */ 
tions that arise when dealing with a fixed document size. The cRect.top = thePort->portRect.top - 1; 
trick thereafter is to ensure that you never stray outside the cRect. left = thePort->portRect.right - SCROLLSIZE; 
document - see DoGrowWindow() etc */ cRect.bottom = thePort-»portRect bottom - 14; 
void  MakeTwoWindowsC) cRect.right = thePort->portRect.right + 1; 

{ cH = NewControl(thePort,&cRect, “АР”, TRUE, 

int i, topGap, winWidth, winHeight; 0,0, vertRenge,scrollBarProc, VSCROLL); 

int horRange, vertRange; if (vertRange == 0) 

Rect boundsRect, cRect, clpRect; HiliteControl(cH, 255); 

WindowPtr wPtr; сірКесі = thePort->portRect; 

ControlHandle cH; clpRect .bottom -= SCROLLSIZE; 

WStateData’ *wsd; clpRect right -= SCROLLSIZE; 

ClipRect(&clpRect); 

/* Old small screen, or something bigger? MakeTwoMeters(wPtr, i2; 

topGap = menu bar height + 20 for the window frame */ 

if ((screenBits.bounds bottom )/* end MakeTwoWindows() */ 

- screenBits.bounds.top) < 343) 

topGap = MBarHeight + 20; /* Create four meters, two in each window. Note that it is not 
else necessaru to carru around all the meterhandles as globals 

topGap = 60; since theu are attached to the window’s refCon field as a 
/* topGap + window height + all offsets(1x1@ here) + 4Cat linked list by NewMeter(). */ 

the bottom) = screen height */ void  MakeTwoMeters(wPtr, which) 
winHeight = C(screenBits.bounds.bottom - WindowPtr wPtr; 
screenBits.bounds.top - topGap - 14) int which; 
<= MAXWINDOWHEIGHT) ? 
(screenBits.bounds.bottom - Rect boundsRect; 
screenBits.bounds.top - topGap - 14) : MeterHandle mH; 
МАХИ INDOWHE IGHT; 
winWidth = CCscreenBits.bounds.right if (which == 1) 
- screenBits.bounds. left - 18) 
<= MAXWINDOWWIDTH) ? boundsRect.top = 0; 
(screenBits.bounds.right - boundsRect. left = 0; 
screenBits.bounds. left - 18) : boundsRect.bottom = 0; 
MAXWINDOWWIDTH; boundsRect.right = 144; /* 2 inches wide */ 
setRect(&boundsRect, 4, topGap, 4 + winWidth, topGap + mH = NewMeter(wPtr, &boundsRect, mTitlel, 
winHeight); FALSE, 256L, ØL, 5121, ØL); 
/* Scroll bar ranges: range = amount of document (**mH).meterVis = TRUE; 
left unseen Chonest!) */ (**mH).meterHilite = 255; 
vertRange = MAXWINDOWHEIGHT boundsRect.left = 150; 

- CboundsRect .bottom - boundsRect. top); boundsRect right = 222; /* 1 inch wide */ 
vertRange = (vertRange > 0) ? vertRange : 0; mH = NewMeter(wPtr, &boundsRect, mTitle2, 
horRange = MAXWINDOWWIDTH FALSE, OL, -1000L, 1000L, ØL); 

- CboundsRect.right - boundsRect.left); (**mH).meterVis = TRUE; 
horRange = ChorRange > 0) ? horRange : 0; (**mH).meterHilite = 255; 

/* Create two windows, offset slightly */ 
for Ci = 1; i <= 2; ++i) ыен (which == 2) /* the front window at first */ 
if (i == D boundsRect.top = 10; 
wPtr = NewWindow(&wRecord!, &boundsRect, boundsRect.left = 50; 
wlitlel, TRUE, 8,- 1L, TRUE, ØL); boundsRect.bottom = 0; 
else boundsRect right = 158; 
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NewMeter(wPtr, &boundsRect, mTitle3, TRUE, 
2000L, OL, 4095L, 01); 
boundsRect.left = 204; 
boundsRect.right = 384; 
NewMeter(wPtr, &boundsRect, mTitle4, TRUE, 
ØL, -40950L, 40950L, ØL); 


) 
)/* end MakeTwoMeters() */ 
/* Shake the needle around the setpoint to see it move. 


Affects all meters in the front window. */ 
void DitherMeters() 
{ 


Static int random = 0; 

static long oldVal = ØL; 

long val, setVal, posIncrement, newVal; 
int direction, досу, docH; 


ControlHandle cHH, cHV; 
MeterHandle mH = 
(Me terHandle )((CWindowPeek )thePort )->refCon); 


1f CValidMeter(mH)) 


( 
Delau(@L, knewVal); 
M us - oldVal > 8L) /* time delay */ 


і? (random › 0) 
direction = 1; 
else 1f (randon « 0) 
direction = -1; 
else 
direction = 0; 
oldVal = newVal; 
/* get control handles */ 
GetScrollHandles(thePort, &cHH, &cHV); 
/* find where we’ve scrolled to */ 
docV = GetCtl]Value(cHV); 
docH = GetCtlValueCcHH); 
/* shift to the right location in the document */ 
SetüriginCdocH, docV); 
OffsetRgnCthePort-»clipRgn, docH, досу); 
/* run through all the meters for this window */ 
while (ValidMeter(mH)) 


val = (**mH).needleValue; 

setVal = (**mH).meterValue; 

posIncrement = 

C(C**mH).meterMax - (**mH).meterMin2/250L ; 

newVal = val +CsetVal - val2/10L* direction *posIn- 
crement; 

SetNeedleValue(mH, newVal); 

mH = C**mH).nextMeter; 


) 
SetOrigin(0, 0); 
Of fsetRgn(thePort->clipRgn, -docH, -docV); 
++random; 
if (random >= 5) 
random = -5; 


) 
)/* end DitherMeters() */ 


/* Handle Mouse in window -can hit scroll bars or meters. */ 
void DoContent(theWindow, theEvent) 


WindowP tr theWindow; 
EventRecord*theEvent ; 
. int cntlCode, axis; 
int docV, docH; 
int oldMWidth, newMWidth; 
Point startPoint, endPoint; 


ControlHandle theCt], cHH, cHV; 
MeterHandle  theMeter; 
Rect limitRect, slopRect; 
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startPoint = theEvent- where; 
GlobalToLocal (&star tPoint); 
/* First handle scroll bar events... */ 
if (CentlCode = 
FindControl(startPoint, theWindow,&theCt1)2!z0) 


( 
if (cntlCode >= inUpButton && 
cntlCode <= inPageDown) /* not thumb */ 
TrackControlCtheCtl,startPoint,&ScrollProc); 
else if (cntlCode == inThumb) 


/* Ordinarily you would call 
TrackControlCtheCtl,startPoint, ØL) but today we're doing 
“real-time” thumb control. */ 

ThumbControlCtheCtl, startPoint); 

) /* else if in thumb */ 

) /* if in a control */ 

/*...then handle “true content” mouse events. */ 
else 

( 

/* We're going to treat the meters as being 
attached to the underluing document rather than the window 
frame, so we must shift to “document” coordinates before 
determining which meter was hit. */ 

LocalloDoc(&startPoint); 

if ((cntlCode = 

FindMeter(startPoint, theWindow, &theMeter ))!=0) 


/* Shift everything to document coordinates 

before proceeding: */ 

/* 1 - get control handles */ 

GetScrollHandlesCtheWindow, &cHH, &cHV); 

/* 2 - find where we've scrolled to */ 

docV = GetCtlValueCcHV); 

docH = GetCtlValueCcHH); 

/* 3 - shift to the right location in the document */ 

SetOriginCdocH, docV); 

OffsetRgnCtheWindow-?clipRgn, docH, docV); 

/* 4 - now deal with events as though no scrolling has 
taken place */ 

ч cds E & optionKey) 


/* Drag the meter around. This is very handy 
Since meters take up a lot ofscreen. Unneeded meters can be 
slid almost entirely off the screen to make room for other 
things. */ 

slopRect = limitRect = thePort->portRect; 

InsetRect(&limitRect, 10, 10); 

limitRect.right -= SCROLLSIZE; 

limitRect.bottom -= SCROLLSIZE; 

axis = 0; /* no constraint */ 

DragMeter(theMeter, startPoint, 

&limitRect, &slopRect, axis); 


) 
else if (theEvent modif iers & cmdKeu) 


/* Resize the meter while mouse down - useful when 
playing with the look of the meter, and shows how the display 
box can be a very handy design tool. */ 

oldMWidth = (**theMeter).meterRect right 

- (**theMeter).meterRect. left; 
ыы (StillDown()) 


GetMouse(&endPoint); /* in unscrolled coord s */ 
newMWidth = oldMWidth - startPoint.h + endPoint.h; 
SizeMeter(theMeter, newMWidth); 
DrewDisplagBoxCtheWindow, Cvoid**)theMeter, 
forMeter, 0,0); 


else if (спі1Соае >= inUpButton && 
cntlCode <= inPageDown) /* not background */ 
TrackMeter(theMeter,startPoint, &MeterProc); 
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else if (cntlCode == inBackground) 


/* default for inBackGround just shows set 
point value */ 
Шаа Sis 


SetOrigin(0, 0); 
Of fsetRgn( theWindow->clipRgn, -docH, -docV); 
) /* if FindMeter */ 
) /* else true content */ 
) /* end DoContent() */ 


/* The all-purpose redraw function, draws only what touches 
the update region and handles scroll bars so that the routines 
which draw individual items don't have to keep track of where 
we've scrolled to in the document. Can even be used for 
printing, provided you temporarily set the scroll bar values 
to the minimum and the updateRgn to the whole document 
beforehand, and provided your individual drawing routines 
don't set theport before drawing. */ 

void UpdateContents(wPtr, frontMost) 

WindowPtr wPtr; 


Boolean frontMost; 
int docV, docH; 
Rect clpRect; 


ControlHandlecHH, cHV; 
MeterHandle mH = (MeterHandle)((CWindowPeek wPtr)-»refCon); 


SetClipCupdateRgn); 

/* get control handles */ 

GetScrollHandlesCwPtr, &cHH, &cHV); 

/* find where we’ve scrolled to */ 

досу = GetCtlValueCcHV); 

docH = GetCtlValueCcHH); 

/* shift to the right location in the document*/ 
E ue || docH) 


SetOriginCdocH, docV); 
Of fsetRgnCwPtr->clipRgn, docH, docV); 


/* we’ll be ultra-efficient and draw only what 
touches the updateRgn */ 
while (mH) 


( 
if (RectInRgn(&((**mH).meterRect), wPtr->clipRgn)) 


/* Fool ShowMeter() into redrawing the meter. */ 
(**mH).meterVis = FALSE; 
en 


mH = (**mH).nextMeter; 


1f (досу || docH) 
SetOrigin(0, 0); 
clpRect.top = wPtr- portRect top; 
clpRect.left = wPtr->portRect. left; 
clpRect.bottom = wPtr-»portRect.bottom - SCROLLSIZE; 
clpRect.right = wPtr- portRect.right - SCROLLSIZE; 
ClipRectC&clpRect?); 
) /* end UpdateContents() */ 


/* Show two integer values in a little display box at bottom 
right of the window. If you call this function with mode = 
forDebug, specify the WindowPtr and put the two values in 
newValue and otherValue. */ 
void DrawDisplayBoxCwPtr, theHandle, mode, 

newValue, otherValue) 


WindowPtr wPtr; 
void **theHandle; 
DisplagMode mode; 
int newValue, otherValue; 
int i, j; 
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int oldFont, oldSize; 
Stule oldStule; 

1ong leftNum, rightNum; 
char s[20], sr[10], *sPtr; 
Rect displauRect, clpRect; 


MeterHandle mH; 
ControlHandle theCtl, cHH, cHV; 
GrafPtr savePort; 


1f (DISPLAYBOXWIDTH <= Ø) return; 
GetPort(&savePort); 
SetPort(wPtr); 
oldFont = wPtr->txFont; 
oldSize = wPtr->txSize; 
oldStyle = wPtr->txFace; /* sic */ 
TextFontC0); 
TextSize( 12); 
TextFaceC^ '); 
displayRect.top = wPtr-?portRect.bottom - SCROLLSIZE + 1; 
displayRect. left = wPtr->portRect.right 

- DISPLAYBOXWIDTH - 14; 
displayRect.bottom = wPtr->portRect bottom + 1; 
displayRect.right = displayRect. left 

+ DISPLAYBOXWIDTH - 1; 
ClipRect(&displayRect); 
EraseRect(&displayRect); 


1f (mode == forWindow) 


GetScrollHandles(wPtr, &cHH, &cHV); 

leftNum = Clong2GetCtlValueCcHH); 

rightNum = Clong2GetCtlValueCcHV); 

/* or try 

leftNum = wPtr->portRect.right - wPtr->portRect.left - 15; 
rightNum = wPtr->portRect.bottom - wPtr->»portRect.top - 


*/ 


15; 


“н if (mode == forMeter) 


mH = (MeterHandle)theHandle; 
lef tNum = Clong)(C**mH) .meterRect.right 
- (*¥mH).meterRect. left); 
rightNum = Clong)CC**mH).meterRect bottom 
- (**mH).meterRect.top); 


else if (mode == forThumb) 
GetScrollHandles(wPtr, &cHH, &cHV); 
theCt] = (ControlHandle)theHandle; 
ыа == cHH) 


leftNum = (long)newValue; 
rightNum = Clong2GetCtlValueCcHV); 
) 


us 
leftNum = Clong2GetCtlValueCcHH); 
rightNum = Clong)newValue; 
else if (mode == forDebug) 


lef tNum = Clong)newValue; 
еш = (long?otherValue; 


else 


leftNum = ØL; 
rightNum = ØL; 
) 


NumloString(leftNum, s); 


NumloString(rightNum, sr); 
/* Concatenate sr into s with space between. */ 


@ The Best of MacTutor, Vol. 5 


2 
for (i = 1, sPtr = k(s[j + 11); i <= sr[0]; ++i) 
*sPtr++ = sr[il; 
510] += i; /* note 1 extra for space */ 
TextBox(&(s[1)), (Bute)(s[0]), &displayRect, 
teJustCenter); 


clpRect.top = thePort->portRect. top; 

clpRect.left = thePort->portRect. left; 

clpRect.bottom = thePort->portRect.bottom - SCROLLSIZE; 
clpRect.right = thePort->portRect.right - SCROLLSIZE; 
ClipRectC&clpRect); 

Tex tFontColdFont); 

TextSizeColdSize); 

TextFaceColdStyle); 

SetPort(savePort); 

) /* end DrawDisplayBox() */ 


/* Both DoZoomWindowC) and DoGrowWindowC) handle the poten- 
tially embarrassing problem of moving around in a document of 
fixed size without scrolling out into the Twilight Zone. */ 
void  DoZoomWindow (wPtr, part) 

WindowPtr wPtr; 


int part; 
int oldV, oldH, newV, newH; 
int vertRange, horRange; 
int curValH, curMaxH, curValV, curMaxV; 
Point 05; 


ControlHandlecHH, cHV; 


/* get control handles */ 

GetScrollHandles(wPtr, &cHH, &cHV); 

oldV = CwPtr->portRect).bottom - CwPtr->portRect). top; 
oldH = CwPtr->portRect).right - CwPtr->portRect). left; 


curValH = GetCtlValue(cHH); 
curMaxH = GetCtMaxCcHH2; 
curValV = GetCtlValueCcHV); 
curMaxV = GetCt]Max(cHV); 


ZoomWindow(wPtr, part, TRUE); 

InvalRectC&CwPtr-?portRect 2); 

newV = CwPtr->portRect).bottom - CwPtr->portRect). top; 

newH = CwPtr->portRect).right - CwPtr->portRect). left; 
SetRectC&CCE*cHV) . contr TRect?, 
wPtr-»portRect.right - SCROLLSIZE, 
wPtr-?portRect.top - 1, wPtr—portRect.right + 1, 
wPtr->portRect.bottom - 14); 

setRect(&CC**cHH).contriRect), wPtr->portRect.left - 1, 
wPtr->portRect.bottom - SCROLLSIZE, 
wPtr->portRect.right - DISPLAYBOXWIDTH - 14, 
wPtr->portRect.bottom + 1); 

vertRange = MAXWINDOWHEIGHT - 

(wPtr-»portRect.bottom - wPtr->portRect. top); 

vertRange = (CvertRange > Ø) ? vertRange : 0; 

horRange = MAXWINDOWWIDTH - 

CwPtr->portRect.right - wPtr->portRect. left); 

horRange = ChorRange ? 0) ? horRange : 0; 

SetCtlMaxCcHV, vertRange); 

SetCtlMax(cHH, horRange); 

if CvertRange == 0) 

HiliteControlCcHV, 255); 
else 

HiliteControlCcHV, 0); 
if ChorRange == 0) 

HiliteControlCcHH, 255); 

else 
— HiliteControlCcHH, 0); 

/* “Scroll” if running off the bottom or right. The whole 
window has been invalidated above, so we just shift scroll 
bars & then let update event take care of redrawing later. */ 

/* dS.hCor .v) = overshoot = amount potentially exposed 
by zoom less amount available to be exposed; potential amount 
= increase in window size; amountavailable = maximum amount 
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left unseen, which is the (prezoom) control Max, less amount 
that has already scrolled by, which is the (prezoom) control 
Value. If you grok that, you’ve got scroll bars in the bag! */ 


dS.h = newH - oldH - curMaxH + curValH; 
dS.h = (dS.h > 0) ? dS.h : Ø; 
dS.v = newV - oldV - curMaxV + curValV; 
dS.v = (dS.v > 0) ? dS.v : Ø; 


if (dS.h> Ø || dS.v > 0) 


SetCtlValueCcHV, GetCtlValueCcHV) - dS.v); 
ү е GetCtlValue(cHH) - dS.h); 


) /* end DoZoomWindow() */ 


void DoGrowWindowCevent) 
EventRecord  *event; 


int winWidth, winHeight; 

int horRange, vertRange; 

int oldV, oldH, newV, newH; 

int curValH, curMaxH, curValV, curMaxV; 
long growResult; 

Point ds; 

Rect limitRect, badRect; 

ControlHandlecHH, cHV; 

RgnHandle tempRgn; 

WindowPtr wPtr = FrontWindow(); 


winHeight = (CscreenBits.bounds. bottom 
- screenBits.bounds.top - 22) 
<= MAXWINDOWHEIGHT) ? CscreenBits.bounds.bottom 
- screenBits.bounds.top - 22) : MAXWINDOWHEIGHT 
winWidth = ((screenBits.bounds.right 
- screenBits.bounds. left - 2) 
<= MAXWINDOWWIDTH) ? (CscreenBits.bounds.right 
- screenBits.bounds.left - 2) : MAXWINDOWWIDT 
limitRect.top = 130; 
limitRect.left = 250; 
limitRect.bottom = winHeight + 1; 
limitRect.right = winWidth + 1; 
/* get control handles */ 
GetScrollHandles(wPtr, &cHH, &cHV); 
oldV = CwPtr->portRect).bottom - CwPtr->portRect). top; 
oldH = CwPtr->portRect).right - CwPtr->portRect). left; 


curValH = GetCtlValueCcHH); 
curMaxH = GetCtMaxCcHH); 
curValV = GetCtlValueCcHV); 
curMaxV = GetCt1MaxCcHV2; 


growResult = GrowWindow(wPtr, event- where, &limitRect); 
newV = HiWordCgrowResult); 
newH = LoWord(growResult); 
SizeWindow(wPtr, newH, newV, TRUE); 
ClipRect(&CwPtr->portRect)); 
SetRectC&CC**cHV).contrTRect?, 
wPtr->portRect.right - SCROLLSIZE, 
wPtr-?portRect.top - 1, 
wPtr->portRect.right + 1, 
wPtr-—portRect.bottom - 14); 
SetRect(%&((**cHH).contrlRect), wPtr->portRect.left - 1, 
wPtr->portRect.bottom - SCROLLSIZE, 
wPtr->portRect.right - DISPLAYBOXWIDTH - 14, 
wPtr->portRect.bottom + 1); 
vertRange = MAXWINDOWHEIGHT - 
CwPtr->portRect bottom - wPtr->portRect. top); 
vertRange = (vertRange > 0) ? vertRange : 0; 
horRange = MAXWINDOWWIDTH - 
CwPtr->portRect.right - wPtr->portRect. left); 
horRange = ChorRange > 0) ? horRange : 0; 
SetCtlMax(cHV, vertRange); 
SetCtlMax(cHH, horRange); 
if (vertRange == Ø) 
HiliteControl(cHV, 255); 
else 
HiliteControl(cHV, 0); 


2 


H; 
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1f (horRange == 0) if (wPtr == CWindowPtr )(&wRecord!) 11 


HiliteControlCcHH, 255); wPtr == CWindowPtr )(&wRecord2)) 
else return (TRUE); 
HiliteControlCcHH, 0); return(FALSE); 
/* update scroll bars properly */ ) /* end AMeterWindow() */ 
і? (new > oldV) 
{ void  GetScrollHandles(wPtr, cH, cV) 
'badRect.top = oldV - SCROLLSIZE; WindowPtr wPtr; 
badRect.left = 0; ControlHandle *cV, *cH; 
badRect.bottom = oldV; 


badRect.right = oldH; ControlHandlecHH, cHV; 
InvalRectC&badRect); 
) 


cHH = CCWindowPeek wPtr)->controlList; 


else “” (cHH) 
bedRect.top = (wPtr->portRect).bottom - SCROLLSIZE; if (GetCRefCon(cHH) == HSCROLL) break; 
badRect.left = CwPtr->portRect). left; cHH = (**cHH).nextControl; 
badRect.bottom = (wPtr-,portRect).bottom; 
badRect.right = CwPtr->portRect).right; СНУ = CCWindowPeek wPtr )->controlList; 
InvalRect(&badRect ); шы (cHV) 
1f (newH > oldH) 1f (GetCRefCon(cHV) == VSCROLL) break; 
( СНУ = (**cHV).nextControl; 
badRect.top = 0; ) 
badRect.left = oldH - SCROLLSIZE; *cH = cHH; 
badRect.bottom = oldV; *cV = cHV; 
badRect.right = oldH; ) /* end AMeterWindow() */ 
InvalRect(&badRect); 
) void LocalloDoc(thePt) 
. i *thePt; 
badRect.top = (wPtr->portRect). top; ControlHandle cHH, cHV; 
badRect. left = CwPtr->portRect).right - SCROLLSIZE; 
badRect .battom = CwPtr->»portRect).bottom; /* get control handles */ 
badRect.right = CwPtr->portRect).right; GetScrollHandlesCthePort, &cHH, &cHV); 
InvalRectC&badRect); /* Document coordinates are always at least as large as 
local coord’s - a mental picture: the window sliding over the 
badRect.top = CwPtr->portRect). top; document helps. */ 
badRect. left = CwPtr->portRect). left; thePt->v += GetCtlValueCcHV); 
badRect.bottom = CwPtr-»portRect). bottom - SCROLLSIZE; thePt-»h += GetCtlValue(cHH); 
badRect right = CwPtr->portRect).right - SCROLLSIZE; ) /* end LocalToDoc() */ 
/* Scroll if running off the bottom or right of document. 
The newly exposed part is invalidated.The resulting update void MeterProc(mH, theCode) 
event will set updateRgnequal to the total invalidated region, MeterHandle mH; 
and UpdateContents() will redraw only that part of window. */ int theCode; 
dS.h = newH - oldH - curMaxH + curValH; ( 
dS.h = (dS.h > 0) ? dS.h : 0; long posIncrement = ((**mH).meterMax 
dS.v = newV - oldV - curMaxV + curValV; - (**mH).meterMin)/250L; 
dS.v = (dS.v > 0) ? dS.v : Ø; long scrollAnmt; 


if (dS.h > Ø || dS.v > 0) 
Delau(2L, kscrollAmt); 


ClipRect(&badRect); switch (theCode) 
tempRgn = NewRgn(); 
SetCtlValueCcHV, GetCtlValue(cHV) - dS.v); case inUpButton: 
SetCtlValueCcHH, GetCtlValue(cHH) - dS.h); scrollAmt = poslncrement/10L; 
ScrollRect(&badRect, dS.h, dS.v, tempRgn); if C!scrollAmt) 
InvalRgnCtempRgn); scrollAmt = IL; 
DisposeRgn(tempRgn); break; 
) case inDownButton: 
else scrollAmt = -posIncrement/10L ; 
ClipRect(&badRect); if (!scrollAmt) 
) /* end DoGrowWindow() */ scrollAmt = -1L; 
break; 
void DoCloseWindow() case inPageUp: 
scrollAmt = posIncrement; 
WindowPtr wPtr = FrontWindow(); break; 
case inPageDown: 
KillMetersCwPtr); scrollAmt = -posIncrement; 
CloseWindow(wPtr); /* does KillControlsC) for you */ break; 


) /* end DoCloseWindow() */ 
SetMtrValue(mH, GetMtrValue(mH) + scrollAmt?; 
Boolean  AMeterWindow(wPtr) ) /* end MeterProc() */ 
WindowPtr wPtr; 
( pascal void ScrollProc(theCt]1, partCode) 
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ControlHandle theCt1; 

By par tCode; 
int delta, pageSize, arrowSize, oldValue; 
Point dS; 


Rect viewBnds; 
Boolean horizontal = FALSE; 


/* which control, how far */ 
1f (GetCRefCon(theCt1) == HSCROLL) 
{ 


= TRUE; 
CthePort->portRect). right 
- CthePort->portRect). left - SCROLLSIZE; 


horizontal 
pageSize = 


) 
else /* VSCROLL */ 
pageSize = CthePort->portRect). bottom 
- CthePort->portRect).top - SCROLLSIZE; 
arrowSize = pageSize/20; 

/* delta is used to adjust local coord’s, which DECREASE 
if up button pressed (we move closer to top of document). 
However, we want the stuff in the window to slide DOWN so the 
sign of dS isreversed from that of delta in order that 
ScrollRect() will work correctly. Hence for up button of 
vertical scroll, delta is negative andijS.v is positive (theu 
agree in magnitude unless we're at one end or the other of the 
document). */ 

switch (partCode) 


case inUpButton: 

delta = -arrowSize; 
break; 
case inDownButton: 

delta = arrowSize; 
break; 
case inPageUp: 

delta = -pageSize; 
break; 
case inPageDown: 

delta = pageSize; 
break; 
default: 

delta = @; 
break; 

) /* end switch */ 
ClipRectC&CthePort-»portRect22; 
oldValue = GetCtlValueCtheCt1); 
SetCtlValueCtheCtl, oldValue + delta); 
Шы 


dS.h = oldValue - GetCtlValueCtheCt!1); 
dS.v = 0; 


iru /* vertical */ 


dS.v = oldValue - GetCtlValueCtheCt12); 
dS.h = Ø; 
) 


viewBnds.top = (thePort->portRect). top; 
viewBnds.left = (thePort->portRect). left; 
viewBnds.bottom = CthePort-»portRect).bottom 
- SCROLLSIZE; 
viewBnds.right = (thePort->portRect).right 
- SCROLLSIZE; 
/* To speed redrawing up, you could just 
set updateRgn equal to viewBnds and callUpdateContentsC) 
without scrolling if the partCode was for paging- however this 
gives the user less visual feedback. */ 
/* ScrollRect() both moves the screen image and accumulates 
the freshly exposed region in updateRgn. */ 
ScroliRect(&viewBnds, dS.h, dS.v, updateRgn); 
DrewDisplayBoxCthePort, ØL, forWindow, 0,0); 
UpdeteContentsCthePort, TRUE); 
) /* end ScrollProcC) */ 
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/* This function will track the mouse and correctly update the 
value of a scroll bar as the thumb is dragged around, in case 
you might want to update a graphic or number continuously as 
the user moves the thumb about, something TrackControlC) 
doesn't readily allow. Use "ThumbControl(startPoint, theCt1);” 
in place of “if (TrackControlCtheCtl,startPoint, 0122” when 
FindControl() reports an appropriate thumb event, and modify 
the action calls in this routine where indicated. Depending on 
your needs, you may want to clip differently. For generality, 
this routine decides which scroll bar is which by the same 
method that the Contro! Manager uses - which way is longer? 
Much of “while CStillDownC22^ below is а duplication of 
DragGrayRgn() that lets us tell where we are at all times. */ 
void ThumbControlCtheCt], startPoint) 


ControlHandle theCt1; 

Point stertPoint; 
int newValue, startValue, thickness; 
int mouseRange, controlMin, controlMax; 


long  thumbRange, controlRange; 
Point theMouse, thumbStart, thumbMin, 

thumbMax, newThumbCent, thumbCent, halfThumb; 
Rect  controlRect,slopRect, startRect, thumbRect; 
RgnHandle oldClipRgn; 
PenState pState; 
Boolean isHorizontalBar, tracking; 


GetPenState(&pState); 

PenMode(patXor ); 

PenPat(dkGray); 

PenSizeC1, 1); 

controlRect = (**theCt1).contr Rect; 

slopRect = controlRect; 

controlMin = GetCtIMin(theCt1); 

controlMax = GetCtlMaxCtheCt1); 

controlRange = Clong)(controlMax - controlMin); 

startValue = GetCtlValueCtheCt1); 

newValue = startValue; 

isHorizontalBar = 
(controlRect.right - controlRect.left) > 
(controlRect.bottom - controlRect.top) ? 
TRUE : FALSE; 

if CisHorizontalBar) 


thumbStart.v s'controlRect.top + 
(controlRect.bottom - controlRect.top + 12/2; 
thumbMin.v = thumbMax.v = thumbStart.v; 


thickness = controlRect.bottom - controlRect.top; 
halfThumb.h = thickness/2; 
halfThumb.v = halfThumb.h - 1; 


thumbMin.h = controlRect. left 

+ thickness + (thickness + 12/2; 
thumbMax.h = controlRect.right 

- thickness - (thickness + 12/2; 
thumbRange = (long)CcontrolRect.right 

- controlRect.left - 3*thickness); 
thumbStart.h = thumbMin.h 

+ (thumbRange*(startValue - controlMin) 

+ controlRange/2)/controlRange; 
ИЕ -12, -36); 


else 
( 


thumbStart.h = controlRect.left + 
(controlRect.right - controlRect.left + 1)/2; 
thumbMin.h = thumbMax.h = thumbStart.h; 
thickness = controlRect.right - controlRect.left; 
halfThumb.v = thickness/2; 
halfThumb.h = halfThumb.v - 1; 
thumbMin.v = controlRect.top 

+ thickness + (thickness + 12/2: 
thumbMax.v = controlRect.bottom 

- thickness - (thickness + 12/2; 
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thumbRange = (long)(controlRect.bottom 

- controlRect.top - 3*thickness); 
thumbStart.v = thumbMin.v 

+ CthumbRange*(startValue - controlMin) 

+ controlRange/2)/controlRange; 
InsetRect(&slopRect, -36, -72); 


) 

і? CthumbRange <= 0) return; /* that’s a pretty 
short scroll ber */ 

newThumbCent = thumbCent = thumbStart; 

oldClipRgn = NewRgn(); 

GetClipColdCl ipRgn)2; 

ClipRectC&controlRect); 

SetRect(&thumbRect, thumbCent.h - halfThumb.h, 

thumbCent.v - halfThumb.v, thumbCent.h * halfThumb.h, 
thumbCent.v + halfThumb.v); 
tracking = FALSE; 
while (Stil 1Down()) 


ClipRectC&controlRect); 

GetMouseC&theMouse); 

if (PtInRect(theMouse, &slopRect)) 
( /* mouse is close to scroll bar - track the thumb */ 
/* calculate new thumb center */ 
Шаа ыы 


newThumbCent.h = thumbStart.h 
+ XtheMouse.h - startPoint.h); 
1f (newThumbCent.h < thumbMin.h) 
newThumbCent.h = thumbMin.h; 
else if (newThumbCent.h > thumbMax.h) 
newThumbCent.h = thumbMax.h; 


else 


newThumbCent.v = thumbStart.v 
+ (theMouse.v - startPoint.v); 
if (newThumbCent.v < thumbMin.v) 
newThumbCent.v = thumbMin.v; 
else if (newThunbCent.v > thumbMax.v) 
newThumbCent.v = thumbMax.v; 


) 
и 


1f (newThumbCent.h != thumbCent.h || 
newThumbCent.v != thumbCent.v) 


( 

FrameRect(&thumbRect ); 

SetRect(&thumbRect, newThumbCent.h - half Thumb.h, 
newThumbCent.v - halfThumb.v, 
newThumbCent.h + half Thumb.h, 

newThumbCent.v + half Thumb.v); 

үтте киыр 


else /* just entering slop rect */ 


SetRect(&thumbRect, 
newThumbCent.h - halfThumb.h, 
newThumbCent.v - halfThumb.v, 
newThumbCent.h * halfThumb.h, 
newThumbCent.v + halfThumb.v); 
FrameRect(&thumbRect); 
tracking = TRUE; 


) 
) /* if track the thumb */ 
else /* not in slop rect */ 


if (tracking) 
( /* just leaving slop rect */ 
FrameRectC&thumbRect); 
tracking = FALSE; 
jm = thumbStart; 
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) /* else default to start position */ 
1f (newThumbCent.h != thumbCent.h || 
newThumbCent.v != thumbCent.v) 


/* Either thumb has been dregged to new position or 
mouse has left slopRect, in which case thumbCent reverts to 
thumbStart. */ 

/* Calculate control value based on newThumbCent. */ 

newValue = CcontrolRange*CnewThumbCent .h 

- thumbMin.h * newThumbCent.v - thumbMin.v) 
+ thumbRange/2)/thumbRange + controlMin; 
thumbCent = newThumbCent; 

/ XX Xxckcocoeoeecoececoooeeoopboeoceoeceoceeeeeee / 

/* Insert your custom call here - the current control value is 
*newValue^; reset clipRgn if you draw outside scroll bar!*/ 
/* Sample thumb action; echo control values to display box. */ 


DrawDisplayBox( thePor t, (void** )theCt1, for Thumb, newValue, 8); 
[FXXXXXXXXXXXEEEEEEEEEEXXXXXXXXXXXXXXXXEEX/ 


) 
) /* while still down */ 
if (tracking) 
FrameRectC&thumbRect); 
if (newValue != startValue) 


SetCtlValueCtheCtl, newValue); 

/* The control value has changed on mouseup to “newValue” 
- take appropriate action - here we redraw the whole window, 
but if newValue were close to startValue you could call 
ScrollRect() instead. */ 

таранды 


else 


/* control value hasn’t changed - reset if necessary */; 


SetClipColdClipRgn); 
DisposeRgn(oldClipRgn); 
SetPenStateC&pState); 

) /* end ThumbControlC) */ 


void PutMetersOnClipCwPtr ) 
WindowP tr wPtr; 
( 


Rect theClipRect; 
PicHandle clipPicH; 
RgnHandle oldClipRgn; 


MeterHandlemH = (MeterHandle)(CCWindowPeek )wP tr )->»refCon); 


ZeroScrap(); 

theClipRect.top = 0; 
theClipRect. left = 0; 
theClipRect.bottom = DOCHEIGHT; 
theClipRect.right = DOCWIDTH; 
oldClipRgn = NewRgn(); 
GetClipColdCl ipRgn); 
ClipRectC&theCl ipRect); 


/* draw the picture */ 
clipPicH = OpenPictureC&theCl ipRect); 
while (ValidMeter(mH)) 

( 


MeterSnapshot(mH); 

) = (**mH).nextMeter; 
ClosePicture(); 
/* put it on the scrap and clean up */ 
HLock(clipPicH); 
PutScrap(GetHandleSize(clipPicH), ‘PICT’, *clipPicH); 
HUnlock(clipPicH); 
KillPictureCclipPicH); 


SetClipColdClipRgn); 

DisposeRgnColdCl ipRgn?; = 

) /* end PutMetersOnClip() */ Sel 
/* End MeterMain.c */ SEEPS 
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C Workshop 
Alternate Scroll Bar CDEF 


Alexander S. Colwell 
Redondo Beach, CA 
Volume 5, Number 11 


THINK C 


Introduction 

Why another CDEF? MacTutoralready have several articles 
relating to the CDEF. Especially relating to is the excellent 
Designer CDEFs article in April 1989 issue. Having read every 
single MacTutor issue, I’ve never seen a scroll bar CDEF article 
containing sample code! 

I wanted a scroll bar that has two up and down arrow buttons 
on both ends of the scroll bar as shown in Figure 1, rather than 
standard single arrow buttons scroll bar. My primary reason for 
a dual arrow buttons scroll bar is for large 19-inch screen 
monitors. I find it’s a real pain to perform simple scrolling 
function whenever your window is fully zoomed-out. I must 
pick-up the mouse several times to get the mouse cursor position 
over the scroll bar’s arrow buttons. Or, I need a large uncluttered 
desk to navigate the mouse cursor over the scroll bar. Anyway, 
enough excuses! 


== Alternate Demo 


Hello, World. This is a 
sample application d 
demostrating the "Alternate |Ë: 
Scroll Bar CDEF" developed [E 
by Alexander S. Colwell 


Mac Tutor & Magazine 
Copyright o 1989 


Figure 1 


CDEF Definition 

The scroll bar control definition comprises two sections: 
control’s messages and control's color. The messages are 
described in Inside Macintosh Volume I in Control Manager 
chapter. I found I had to read the CDEF description in the Control 
Manager chapter several times before I fully understood it's 
implications on certain issues relating to message relationships 
with the ROM routines. The control's color is described in the 
Inside Macintosh Volume V in Control Manager chapter. ( I only 
had to read this chapter a couple of times relating to the CDEF's 
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color controls. Either I am getting better or the ROM documen- 
tation is getting better. I'm more likely inclined to believe the 
latter ). 

Each of the control messages are described relating to the 
scroll bar definition. I will not reiterate the same description 
found in the Control Manager chapter, but I will attempt to 
describe how the scroll bar definition is related to each of the 
control messages. 


Scroll Bar Layout 

Figure 2 shows how the alternate scroll bar layout would 
appear in the user's application or desk accessory. This is similar 
to the Control Manager chapter in Inside Macintosh Volume I 
description of the standard scroll bar's parts. The functionality 
between the standard scroll bar and this alternate scroll bar is 
identical. The only differences are the appearance of the "up 
arrow" and "down arrow" control parts. 


up arrow 
down arrow 


"page up" region 


thumb 


"Page down" region ——[ 


up arrow 


Figure 2 


Entry Point 


pascal long main(varCode, theControl, 
message, param) 

short varCode;/* Variation ctrl code */ 
ControlHandle theControl; /* Ctrl hdl */ 
short message; /* Ctrl message code  */ 


long param; /* Ctr] parameter code */ 


The scroll bar entry point receives four arguments: varCode, 
theControl, message, and param. This scroll bar definition does 
not have any variation. Therefore the varCode argument is 
nevered used. The “simple button”, “check box”, and “radio 
button” controls are examples of the variation control code 
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usage. 

The theControl variable is the scroll bar's control handle. 
This is where the definition keeps all its necessary data structures 
for various control’s operations. 

The message argument informs the scroll bar to perform the 
necessary control operations. This definition will use all the 
control messages except autoTrack control message. Each mes- 
sage will be fully described in the following sections. 

The param argument is extra information passed with the 
associated control message. The scroll bar definition code is 
type-casted the param’s value before using it. For example, the 
testCntl control message’s param value is “Point” data type 
while the calcCRgns control message’s param value is 
*RgnHandle" data type. The usage of the param’s value is 
described in each of the control message that is used by this scroll 
bar definition. 


drawCntl 

The drawCntl control message comprises the largest chunk 
of code and the most complex portion of the scroll bar definition. 
The different parts of the scroll bar to be drawn depends on 
several combination of the CDEF's param, and ControlRecord's 
contrlVis, contrlValuelcontrlMin/contriMax, and contriHilite 
variables. 

The CDEF's param variable contains different values for 
different parts of the scroll bar operations. Note: Theparam value 
is type-casted as long word. The actual value is 16-bit low word 
quantity. This is not clear in the Inside Macintosh I Control 
Manager chapter but is explained in the Technical Note #196. 
Each param is described in the following: 

param = 0: This indicates that the scroll bar should be 
completely re-drawned during window's update or control's 
transition from an invisible to visible state. 

param = Oxff: This indicates that the scroll bar should 
transition into unhighlited state. The scroll bar's "page up" and 
*page down" and "thumb" parts should be removed from the 
scroll bar. 

param = inPageUp: This indicates that the “page up" region 
should be re-drawned. 

param = inPageDown: This indicates that the “page down" 
region should be re-drawned. 

param = inUpButton: This indicates that the either upper or 
lower *up arrow" should be highlited or unhighlited. If the 
contrlHilite value is equal to zero then the “up arrow" should be 
unhighlited. Otherwise, if the contrlHilite value is equal to non- 
zero, and if the contrlMin and contrlMax values are not the same 
value, then it should highlite the “up arrow" button. Note: The 
altButton variable in the CDEF is used to determined if using the 
upper or lower arrows for highliting or unhighliting purposes. 

param = inDownButton: This indicates that the either upper 
or lower “down arrow” should be highlited or unhighlited. The 
highliting rules are the same as the param's inUpButton case. 


testCntl 
The testCntl message should check if the scroll bar control 
is currently visible then it checks if the mouse is within the 
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control's contriRect rectangle area by comparing the mouse 
location specified by the param's “Point” value. 

If the mouse location is within the control's rectangle area 
then DSTestControl function is invoked to compare the mouse 
location with the different parts of the scroll bar : inPageUp, 
inPageDown, inThumb, both inUpB uttons, and both inDownbut- 
tons. If a matching control part is found then it will return the 
scroll bar'scontrol part. Otherwise, zero is returned indicating no 
scroll bar's part was found. Note: Again, the altButtonvariable is 
set depending on which of the upper and lower arrow buttons 
selected for highliting and unhighliting purposes. 


calcCRgns 

The саісСЕ gns control message should return the specified 
scroll bar part's region. The param's “RgnHandle” value con- 
tains a region handle to be reset to the scroll bar part's region. 
However, there are only two cases this control message is 
invoked. 

First case, the whole scroll bar region indicated by the high- 
order bit of paramis set. Note: The paramregion's high-order bit 
should be cleared before operating on the region handle. Other- 
wise, the CDEF runs a risk of ALA BOMBA country. Techni- 
cally speaking, the param value should not have high-order bit 
set in the region handle due to 32-bit mode addressing future 
implementation. But according to Technical Note #212 the 
solution for this particular problem is to separate the two cases 
into calcCntlRgn and calcThumbR gn control messages equiva- 
lentto this message for System 7.0 and henceforth versions in 32- 
bit mode addressing. 

The second case is the “thumb” scroll bar part request by 
TrackControl ROM function. The TrackControl ROM function 
will invoke the calcCR gns message for the "thumb" outline area 
to be passed onto the DragGrayRgn ROM function for dragging 
the “thumb” part of the scroll bar. One extra thing this message 
should do is set the drag region's pattern used by the Drag- 
GrayRgnroutine. I set /tGray pattern into the global DragPattern 
variable. This is the same pattern used to fill-in the inPageUp and 
inPageDown control parts. 


calcCntiRgn 
The calcCntlRgn control message is equivalent to the 
calcCR gns's first case. 


calcThumbRgn 
The calcThumbR gn control message is equivalent to the 
calcCRgns’s second case. 


initCntl 

The initCntl control message is where any necessary initiali- 
zation required by the scroll bar control. Typically, the control 
definition will allocate one or more data structures to be used 
during the course of the control's operations. 

This scroll bar will allocate DS handle to be used for the 
scroll bar's operation saved into the contriData variable of the 
ControlRecord. During the initialization, the black and light gray 
pattern are initialized. The light gray pattern is used in the 
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“upPage” and “downPage” regions of the scroll bar, and for the 
“thumb” drag region area. The DS’s hasColor variable is initial- 
ized indicating if the monitor has color by using the SysEnvi- 
rons’s hasColorQD variable. The scroll bar definition uses this 
variable to determine if will need to perform color drawing of the 
scroll bar parts. Finally, the contrlAction variable is initialized to 
-1L for the TrackControl’s actionProc parameter “thumb” track- 
ing. 

The DSInitControl routine will be invoked to initialized the 
DS data structure. It’s primary job is to compute the size of the 
“thumb” rectangle area and create the polygon handle equivalent 
to the “up arrow” and “down arrow” buttons. 


dispCntl 
The dispCnil control message informs the scroll bar control 
to release all it’s internal data structures within the controlData 
handle. This scroll bar will release the polygon handles and the 
DS handle to the memory manager. 


posCntl 

The postCntl control message informs the scroll bar defini- 
tion to re-compute the new "thumb" position and re-draw the 
scroll bar with the new "thumb" position. The param's “Point” 
value contains the local-coordinates point position within the 
scroll bar's contrlRect rectangle area. The scroll bar definition 
willlookat the A part of the point for horizontal scroll bar, and use 
v part of the point for vertical scroll bar orientation. 


thumbCntl 
The thumbCntl control message informs the scroll bar defi- 
nition to compute the “thumb” dragging rectangle area. The 
param value contains a pointer to a data structure described in 
DragGrayRgn in Window Manager chapter. Its will briefly 
describe it here: 


struct ( /* Dragging region*/ 
Rect limitRect; /* Limit rect scr1*/ 
Rect slopRect; /* Slop rect scrl */ 
short axis; /* Draw axis ctr] */ 


); 


The scroll bar definition will set the axis variable to hAx- 
isOnly constant for horizontal scroll bar or vAxisOnly constant 
for vertical scroll bar. The limitRect variable is the rectangle area 
comprising the “upPage” and “downPage” rectangle areas. And, 
the slopRect variable is the slop area allowed for the mouse to 
move outside the limit rectangle area. 

The slopRect rectangle area require special calculation base 
on the current mouse position within the “thumb”. Before setting 
up the limit rectangle area, the limitRect.left and limitRect.top 
contain the current mouse position. This is saved into temporary 
mouse point variable to be used in the slop rectangle area 
calculation. The problem is that the slop rectangle area cannot be 
the same as the limit rectangle arca. Or else, the “thumb” 
dragging outline will go over the “up arrow” and “down arrow” 
regions. Hence, the slop rectangle area must be adjusted where 
the mouse position within the “thumb” rectangle area. 
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dragCntl 
The dragCnil control message informs the scroll bar that the 
control or the "thumb" is going to be dragged since, the scroll bar 
has no custom dragging requirements. It returns zero value to 
inform the Control Manager to use the default dragging method. 


autoTrack 

The autoTrack control message is not used by the scroll bar 
definition. Since the initCntl control message initializes the 
ControlRecord’s contriAction to -1L value. This will cause the 
TrackControl call the default control tracking mechanism. Since 
the dragCnil message always return zero value this control 
message is never invoked. Note: I had always been confused on 
the purpose of the dragCntl and autoTrack control message 
combinations. Perhaps, someone could explain this in Apple's 
Technical Note series someday. 


Color descriptions 

The scroll bar CDEF uses the GetAuxCtl ROM routine to 
determine how to color different parts of the scroll bar. The 
CDEF uses four different RGB colors for the control's frame, 
body, text, and thumb parts. 

Thecontrol's frame coloris the outline parts of the scroll bar, 
arrows, up & down page regions, and thumb. The control's body 
color is the inside parts of the arrows, and up & down page 
regions. The control’s thumb color is the inside part of the thumb. 
The text color is not used in this scroll bar definition. Note: 
Standard control buttons uses the control's text color value. 

Accessing the scroll bar's colors is very easy. The Ge- 
tAuxCtl ROM call is used to retrieve the scroll bar's colors. The 
calling proto-type definition is as follows: 


Boolean 
GetAuxCtlCControlHandle theControl, 


AuxCtlHnd] &acHnd12); 


The function will return TRUE indicator if the scroll bar's 
theControl control handle has it's own copy of the color data set. 
Otherwise, FALSE indicates the scroll bar using default color 
data set. The acHndl auxiliary control handle will return the 
scroll bar's color data set. To access the frame, body, and thumb 
RGB colors are shown in the following: 


(*C*acHndl2-»acCTable)-» 
ctTable([cFrameColor].rgb 


(*C*acHnd12-»acCTable)-) 
ctTeble[cBodyColor ].rgb 


Сж(жасНља1 )-› асСТаб1е )-› 
ctTable[cThumbColor].rgb 


I recommend reading Inside Macintosh V’s Control Man- 
ager chapter on more details relating to the control’s color 
displays. There are two main color routines relating to the 
controls : GetAuxCtl and SetCtlColor. 
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Other CDEF Descriptions 

The scroll bar definition uses a weird technique handling 
black & white and color situations. I defined DSDrawObject to 
draw various control's part onto the window. This generic 
routine simplifies the scroll bar definition without worrying if 
drawing black & white or color. And, the DS DrawObject routine 
is coupled with series of macro definitions to perform various 
drawing operations for the scroll bar. 

Finally, I used floating-point to perform various calculations 
to position the “thumb” properly based on the control’s 
contrlValue, contrlMin, and conirlMax variables. I could have 
used fix-integer arithmetic, but I was too lazy to bother with it. 


Scroll Bar Demonstration 
The scroll bar demonstration is a simple text editor applica- 
tion using new THINK C 4.0 Object Library. It’s not great 
American word processor, but it is used to illustrate the Alternate 
Scroll Bar CDEF. 


Wrapping Things Up 

I did not realize how difficult writing a scroll bar definition 
was until writing this CDEF example. I am not for sure this is a 
good alternative scroll bar interface, but it was fun writing it. I 
believe Apple's Human Interface Guidelines are excellent set of 
rules to follow. So how does this scroll bar definition fit into their 
scheme of things? Probably none. However, several of my 
associates at work want a scroll bar definition that varies the size 
of the “thumb” relative to how much visible text (or contents) 
versus hidden text, but I said “It’s almost impossible, since the 
CDEF does not have enough information to determine how to 
vary the ‘thumb’ size.". Anyway, until then onward to other Mac 
programming! 


/* 

x 

x Source - Alternate.c 

* Author - Alexander S. Colwell, 

* Copuright (C) 1989 

* Purpose - This application will demostrate the 

* AlternateCDEF scroll bar using THINK 

* C 4.8 Object Library. 

* 

*/ 
®include ¿“Global.h> /* Global variables x/ 
Sinclude «CApplication.h? /* Application defs x/ 
Sinclude «Commands.» /* Command handler defs */ 
Sinclude «CBartender .h) /* Menu handler defs | 


/* Window handler defs — */ 
/* Window layer hdler def*/ 
/* Document handler defs */ 
/* Text edit handler defs*/ 
/* Scrolling pane defs %/ 


81nclude «CDecorator .h? 
include «CDesktop.h? 
include «CDocument .h> 
include «CEditText.h» 
include «CScrollPane.tv 


struct CAltDemoApp : CApplication (/* Appl object х/ 
void CreateDocument(void);/* Creat new doc method */ 


4 


struct CAltDemoDoc : CDocument {/* Document object х / 
void NewFileCvoid); /* Net (bogus) fil method*/ 


4 


struct CAltDemoPane : CEditText (/* Text pane obj x/ 
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8def ine altWIND 500 


void IEditPaneCCView *anEnclosure, 
CBureaucrat Жабурегуізог 2; 
; 


/* WIND template res ID */ 


/* Define external refs */ 


extern CApplication *gApplication;/* Appl object x/ 


extern CDecorator *gDecorator;/* Window object */ 
extern CDesktop *gDesktop; /% Desktop object */ 
extern CBartender *gBartender;/* Menu object */ 


P mainc) 


gApplication = new(CAl1tDemoApp);/* Creat appln object*/ 
gApplication->IApplication(4,4Ø96L,2048L);/* Init it */ 
gApplication->Run(); /* Startup application x/ 
ИИИ /* Return to da “Finder” */ 


void CAltDemoApp: :CreateDocument() 


CAltDemoDoc *theDocument; /* New document obj */ 


theDocument = new(CAltDemoDoc); /* Create doc object */ 
theDocument-? IDocumentCthis,FALSE);/* Init дос obj */ 
theDocument-? NewF i leC2; /* Create (bogus) doc */ 


void CA1tDemoDoc: :NewF ileCvoid) 


CScrollPane *theScrollPane;/* Scroll pane object  */ 
CAltDemoPane *theMainPane; /* Main pane object x/ 


itsWindow = new(CWindow); /* Create window object */ 
itsWindow-? IWindowCaltWIND,FALSE, gDesktop, this); 


/* Create scrolling object*/ 
theScrollPane = newCCScrollPane); 
theScrol1Pane-? IScrolPane(C i tsWindow, this, 10, 10,0,0, 

SiZELASTIC,SizELASTIC, TRUE, TRUE, TRUE); 
theScrol1Pane->FitToEnclFrameCTRUE, TRUE); 
theMainPane = new(CAltDemoPane); 
itsMainPane = theMainPane; 
itsGopher = theMainPane; 
theMainPane-? IEdi tPaneCtheScrollPane, this); 

theScro11Pane-? InstallPanorama(theMainPane); 


itsWindow- Select); /* Select our window now!*/ 


void CAltDemoPane: : IEditPaneCCView *anEnclosure, 


CBureaucrat *aSupervisor) 


Rect margin; /* Margin rect area */ 

/* Setup text edit stuff */ 

CEditText::IEditTextCanEnclosure, aSupervisor, 1, 1,0,0, 
SizELASTIC,sizELASTIC, 432); 

FitToEnclosureCTRUE , TRUE); 

SetRect(&margin,2,2,-2,-2); 

ChangeSize(&margin, FALSE); 


— 
ж 


Source - AlternateCDEF.c 

Author - Alexander S. Colwell, 
Copuright (C) 1988, 1989 

Purpose - This is a dual-arrow scroll bar control 
definition procedure. It is similiar to 
the standard scroll bar except this has 
two arrow indicators on both ends. 


зе x % x x x x м ж 
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*include <QuickDraw.h> 
*include «Color.h» 
Sinclude <WindowMor .h» 
Sinclude <Contro Mgr .h> 
Sinclude <ToolBoxUtil.h» 
Sinclude «ColorToolBox.h»? 


/* QuickDraw defs x/ 
/* Color defs ж/ 
/* Window Manager defs %/ 
/* Control Manager defs */ 
/* Tool Box Utilities x/ 
/* Color Tool Box defs %/ 


typedef struct ( /* Dual Control x / 
short hasColor; /* Has color monitor flag*/ 
short altButton; /* Using alternate button*/ 
Rect thumb ; /* Thumb rectangle area */ 
Rect cThumb; /* Current thmb rect area*/ 
PolyHandle up; /* Up button handle */ 
PolyHandle down; /* Down button handle x / 
short bLen; /* Button length х/ 
short hBLen; /* Half button length x/ 
short sLen; /* Scroll bar length x/ 
double tFactor; /* Thumb factor x / 
short hFactor; /* Horizontal factor */ 
short vFactor ; /* Vertical factor x/ 
ControlHandle cHd1; /* Ctr] hdl to reference */ 
long blackPat[2]; /* Black pattern х/ 
ed 1tGrayPat (21; /* Light gray pattern x/ 

DS; 
tupedef DS *DSPTR; 


typedef DSPTR *DSHDL; 


tupedef struct ( /* Thumb Info x/ 
ect 


limitRect; — /* Limit rect scrolling */ 
B slopRect; /* Slop rect scrolling  */ 
short axis; /* Drag axis control х/ 
) THUMB; 
typedef THUMB *THUMBPTR; 
/* Misc definitions x/ 
Sdefine NIL (OL) /* NIL pointer x/ 


Sdefine abs(a) (a«0?-a:8) 
Sdefine min(a,b) Ca«b?a:b) 
$def ine naxCa,b) (a<b?b:a) 


/* Absolute macro func  */ 
/* Minumim macro function*/ 
/* Maximum macro function*/ 


/* Trap definitions x/ 
8def ine SysEnvironsTrap 0xa090/* System Enviroment x/ 
8Sdef ine UnknownTrap 0xa89f/* Unknown instruction */ 


/* System 7.0 CDEF msgs */ 
/* Calculate ctn! region */ 
/* Calculate “thumb” гоп */ 

/* Control’s macro procs */ 


"define calcCntiRgn 10 
8def ine calcThumbRgn 11 


Sdef ine DSFrameHUpBtnC) 
DSDrawHB tnCdPtr , dP tr-? up, FALSE) 


Sdef ine DSFrameHDownBtnC) N 
DSDrawHBtn(dPtr,dPtr->down,FALSE) 
Sdef ine DSFrameLUpBtn() \ 


DSDrawLBtn(dPtr,dPtr->up, FALSE) 
Sdefine DSFrameLDownBtn() 

DSDrawLBtnCdPtr ,dPtr-» down, FALSE) 
Sdefine DSFillHUpBtnC) 

DSDrawHBtnCdPtr , dP tr-»up, TRUE ) 
8def ine DSFillHDownBtnC) 

DSDrawHBtn(dPtr,dPtr->down,TRUE) 
Sdefine DSFillLUpBtnC) 

DSDrawLBtn(dPtr,dPtr->up, TRUE) 
&def ine DSFillLDownBtn() 

DSDrawLBtn(dPtr ,dPtr->down, TRUE) 


OO OO Ô — 


8def ine DSFrameBody(a) \ 
DSDraw0b ject(dPtr-» cHd1,DSGetForeGround, 
DSSetForeGround,DSFrameRect, 
cFrameColor,a) 
Sdef ine DSClearBody(a) \ 
DSDrawOb jectCdPtr-?cHd1,DSGetBackGround, 
DSSe tBackGround, DSEraseRect, 
cBodyColor, a) 
Sdef ine DSFillBodyCa) \ 


eo” 


өм Же” 
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DSDrawObjectCdPtr-»cHdl,DSGetBackGround, N 


DSSetBackGround,DSFillRect,cBoduColor,a, \ 
dPtr->1tGrayPat) 
def ine DSFrameThumb(a) \ 
DSDraw0b ject (dP tr->cHd1, DSGetForeGround, \ 
DSSetForeGround, DSFrameRect, \ 
cFrameColor,a) 
Sdefine DSFillThumbCa) \ 
DSDraw0b jectCdP tr-» cHd1, DSGetBackGround, \ 
DSSetBackGround, DSEraseRect, \ 
cThumbColor,a) 
Sdefine DSFrameArrow(a) \ 
DSDraw0bject(dPtr->cHd1, DSGetForeGround, \ 
DSSetForeGround, DSFramePoly, \ 
cFrameColor,a) 
8&def ine DSClearArrow(a) \ 
DSDrawObject(dPtr-,cHd1,DSGetBackGround, \ 
DSSetBackGround, DSErasePoly, \ 
cBodyCo lor, a) 
8def ine DSFillArrow(a) \ 
DSDraw0bject(dPtr->cHd1, DSGetForeGround, \ 
DSSe tForeGround, DSFi11Poly, \ 
cFrameColor ,a,dPtr->blackPat) 
/* Define forward refs  */ 
void DSInitControlC),DSDrawThumbC), DSPosi t ionThumb ), 
DSSetupThumbC), DSDrawHBtnO, DSDrawLBtnCO, 
DSGetBackGround(), DSGe tForeGroundO, 
DSSetBack6roundO, DSSetForeGroundO, 
DSFrameButtons(), DSEraseRectO, DSFrameRectO, 
DSFillRectC) ,DSErasePoly(), DSFramePoly(), 
DSFillPolu(),DSDrawObject(); 
1ong DSTestControlC); 


pascal long main(varCode, theContro1,message, param) 


short varCode; /* Variable control code */ 
ControlHandle theControl; /% Control handle x/ 
short message; /* Control message */ 
1ong param; /* Control parameter x/ 
ControlPtr cPtr; /* Working control ptr  */ 
DSHDL dHd1; /* Working dual ctr! hdl */ 
DSPTR dPtr = NIL;  /* Working dual ctrl ptr */ 
Rect wRect; /* Working scroll area  */ 
SysEnvRec SysEnv; /* Working system envt  */ 
long status = 0;  /* Working status flag  */ 
HLockCtheContro1); /* Lock down the ctr] hd1*/ 
cPtr = *theContro!; /* Set control pointer — */ 


if (message != initCnt1) ( /* Check if already init */ 
if CcPtr->contriData) (  /* Check if valid handle */ 
HLockCcPtr-»contrlData); /* Lock it down for work */ 
aa = *CCDSHDL cP tr->contr1Data); /* Set dual ptr */ 


switch(nessage) ( 
case drawOntl: 


/* Process specified msg */ 
/* Draw the control */ 


if (Ptr) ( /* Check if it’s valid */ 
if (cPtr-bcontrlVis) ( /* Check if it’s visible */ 
PenNormal(); /* Set to normal pen x/ 
switch(LoWord(param)) (/* Switch on control part*/ 
case 0: /* Re-draw scroll bar x/ 
DSInitControlCdPtr,cPtr);/* Re-init it */ 


DSFrameBody(&cPtr->contriRect);/* Init scroll */ 
DSFrameButtons(dPtr); /* Frame the buttons */ 
DSFrameHUpBtnC ); 
DSFrameHDownBtn(); 
DSFrameLUpBtnC); 
DSFrameLDownBtn(); 
DSDrawThumb(dP tr, theControl); break; 

case 129: /* Value/Min/Max changed */ 
DSDrawThumb(dP tr, theControl); break; 

case Oxff: /* Control to be inactive*/ 
DSSetScrollRgnCdPtr,&wRect?; 
DSClearBody(&wRect); break; 
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case inPageUp: /* Hilite scroll bar x/ 
case inPageDown: 
DSDrawThumbCdPtr, theControl); break; 
case inUpButton: /* Hilite high up button */ 
if CdPtr-»altButton) (/* Check if alt button */ 
1f CcPtr->contriHilite == 
cPtr-^contrlMin == cPtr-»contr Max) 
DSFrameLUpBtn(); 
else 
DSF iT 1LUpBtn(); 


else { 
if (cPtr—contrlHilite == Ø || 
cPtr->contriMin == cPtr->contr Max) 
DSFrameHUpBtn(); 
else 
DSF illHUpBtn(2; 


break; 
case inDownButton: /* Hilite high down buttn*/ 
1f (dPtr-»altButton) (/* Check if alt button */ 
if CcPtr->contrlHilite == 0 || 
cPtr-»contrlMin == cPtr->contr 1Max) 
DSFrameLDownBtnC ); 


else 
DSF il 1LDownBtn¢ ); 
else ( 


1f (cPtr->contriHilite == Ø || 
cPtr-»contrlMin == cPtr->contr Max) 


DSFrameHDownBtnC ); 
else 
DSF illHDownBtnC); 
) 
) 
break; 
case testCnt]: /* Test the control */ 
1f (dPtr) /* Check if ptr valid x/ 


if (cPtr->contriHilite |с -1)/* Check if active */ 
if (cPtr-— contr Min != cPtr-»contr1Max) 
if (PtInRectCparam,&cPtr-»contrlRect?) 
status = DSTestControl(dPtr, param); /* Find it */ 
break; 
case calcCRgns: /* Calculate ctr] region */ 
if (dPtr) ( /* Check if pointer valid*/ 
if C!Cparam & 0x80000000L ))/* Check if whole ctr1*/ 


HLockCdHd1); /* Lock it down for init */ 
dPtr = *dHdl; /* Set dual control ptr */ 
dPtr->cHd] = theControl;/* Save it for reference */ 
dPtr->up = dPtr->down = NIL;/* Init poly handles */ 
OPtr->blackPat(@] = OxffffffffL;/* Init patterns */ 
dPtr-»blackPat[1] = OxffffffffL; 
dPtr-»1tGrayPat[0] = 0x88228822L; 
dPtr->1tGrayPatl1)] = 0x88228822L; 
dPtr-^hasColor = FALSE; /* Set to black & white */ 
dPtr-»altButton = FALSE;/* Not using alt button */ 
/* Check SysEnvirons OK */ 
if (Clong)NGetTrapAddress(SysEnvironsTrap, 0STrap)!= 
Clong)NGetTrapAddress(UnknownTrap, ToolTrap)) ( 
SysEnvirons(1,&sysEnv);/* Get system enviroment */ 
dPtr-»hasColor = sysEnv.hasColorQD; /* Save color*/ 


DSInitControlCdPtr,cPtr2;/* Init control’s stuff */ 
cPtr->contrlAction = (ProcPtr2C- 1L2; 
ыны. = (Handle)dHdl1;/* Save data hd] */ 


break; 
case dispOntl: /* Dispose the control */ 
if CdPtr) { /* Check if pointer valid*/ 
if CdPtr->up) /* Kill the polys х/ 
KillPolu(dPtr->up); 
if (dPtr->down) 
KillPolu(dPtr-,down); 
HUnlock(cPtr->contr1Data); /* Unlock it now х/ 
DisposHandle(cPtr-,contrl1Data);/* Return it */ 
cPtr->contriData = NIL; /* Clear it */ 
break; 
case posCnt]: /* Re-position control */ 
1f (dPtr) /* Check if pointer valid*/ 
DSPositionThumbCdPtr, theControl, param); 
break; 


case thumbOntl: /* Calculate for dragging*/ 

if (dPtr) /* Check if pointer valid*/ 

аланы аа Setup for dragging */ 
reak; 


case dragCnt!: /* Drag the control x/ 
status = 0; /* Only drag thumb! */ 
break; 

case autolrack: /* Execute ctrl’s action */ 
break; 


if (cPtr->contr1Data) /* Check if valid pointer*/ 
HUnlockCcPtr-»contr1Data2; /* Unlock for memory mgr */ 


RectRgn((Handle)(param & OxTfffffffL), HUnlockCtheContro1); /* Unlock control handle */ 
&cPtr-?contrlRect); return(status); /* Return status code */ 
else ( /* Want thumb’s region */ 
/* Setup thumb’s area x/ 
RectRgn(CHandle (param & OxTfffffffL), void DSInitControl(dPtr,cPtr) 
&dPtr-»cThumb); DSPTR dPtr; /* Dual control pointer */ 
/* Setup drag pattern x/ ControlPtr СРіг; /* Control pointer x/ 


BlockMoveCdPtr-? 1tGrayPat, DragPattern, 8L 2; 


PolyHandle pHdl; /* Working poly handle  */ 


) short bLen; /* Working button length */ 
break; short hBLen; /* Working 1/2 button len*/ 
case calcCntIRgn: /* Calculate cnt] region */ short hLen; /* Working horizontal len*/ 
if (dPtr) /* Check if ptr valid — */ short vLen; /* Working vertical len */ 

RectRgn( (Handle )Cparam), &cPtr-> contr IRect); short tmp 1, tmp2; /* Working tmp variables */ 

break; Rect cRect; /* Working ctrl rect area*/ 
case calcThumbRgn: /* Calculate “thumb” гоп */ 

if (dPtr) ( /* Check if pointer valid*/ cRect = cPtr->contriRect; /* Set scroll bar area  */ 


/* Setup thumb’s region */ 
RectRgn( (Handle )(param), &dPtr-? cThumb); 


InsetRect(&cRect, 1, 1); /* Shrink it by one-pixel*/ 
/* Set horz & vert lens */ 


/* Setup drag pattern %/ hLen = absCcRect.right - cRect.left) + 1; 
BlockMove(dPtr-> 1tGrayPat, DragPattern, 8L); vLen = abs(cRect.bottom - cRect.top) + 1; 
break; if (hLen > vLen) { /* Check if horz longer */ 


/* Initialized control  */ 
/* Allocate data handle */ 
1f (dHd! = (DSHDL)NewHandle(Csizeof (DS))) ( 


case initCntl: dPtr-»bLen = vLen; /* Set button length x/ 
dPtr-»sLen = hLen + 1;  /* Set scroll bar length */ 


dPtr->hFactor = 1; /* Set horizontal factor */ 
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dPtr-?vFactor = 0; /* Set vertical factor %/ /* Make sure this is max */ 
cPtr-?contrlMax = maxCcPtr-— contr Min, cPtr-— contr 1Max2; 


else ( /* Nope, must be vertical*/ 
dPtr->bLen = hLen; /* Set button length x/ /* Make it min<value<max */ 
dPtr-?sLen = vLen + 1;  /* Set scroll bar length */ cPtr->contriValue = minCcPtr-»contr Max, 
dPtr-»hFactor = 0; /* Set horizontal factor */ naxCcPtr-»contrlMin, cPtr->contr1Value)); 
OPtr->vFactor = 1; /* Set vertical factor */ 

DSSetScrollRgn(dPtr,&wRect);/* Set scroll region — */ 
bLen = dPtr->bLen; /* Set button length х/ /* Init thumb factor calc*/ 
hBLen = dPtr-»hBLen = bLen / 2;/* Set 1/2 buttn len*/ tmp1 = maxCabsCwRect .bottom - wRect.top) * dPtr->vFactor, 
dPtr-> thumb.top = dPtr-»thumb.left = 0;/* Init рі */ abs(wRect.right - wRect.left) * dPtr->hFactor) 
if (dPtr—hFactor) { /* Check if horz position*/ - dPtr->bLen + dPtr->hBLen - 2; 

dPtr-»thumb.bottom = bLen - 1; tmp2 = absCcPtr-»contrlMax - сРіг-әсопігіМіп); 


dPtr->thumb.right = hBLen + hBLen / 2; 
dPtr->tFactor = tmp! / tmp2;/* Set relative factor */ 


else ( /* Nope, vert position */ tmp! = cPtr->contriValue - /*Set thumb pixel offset*/ 
dPtr-?thumb.bottom = hBLen + hBLen / 2; cPtr-?contrlMin; 
dPtr-?thumb.right = bLen - 1; tmp2 = tmp! * dPtr-> tFactor; 
offset = tmp2; 
tmp i = hBLen - 1; /* Set tmp calculations %/ dPtr->cThumb = dPtr->thumb; /* Set thumb rect area */ 
tmp2 = hBLen - 2; OffsetRectC&dPtr-»cThumb, wRect.left + offset * dPtr- 
/* Create up poly handle */ ^hFactor, wRect.top + offset * dPtr->vFactor); 
if (pHd] = OpenPolu()) ( /* Check if got poly hdl */ ) 


if C(dPtr-—hFactor) ( /* Check horz position %/ 


MoveTo(@, tmp 1); void X DSDrawThumbCdPtr, cHd1) 
LineToCtmp2, tmp2 х 2 + 1); DSPTR dPtr; /* Dual control pointer */ 
LineToCtmp2, 1); ControlHandle cHd1; /* Control handle */ 
LineTo(0,tmp1); ( 
) Rect tRect; /* Working thumb area x/ 
else ( /* Nope, vert position */ ControlPtr  cPtr = *cHdl; /* Working control ptr  */ 
МоуеТоСітр1,0); 
LineTo(1,tmp2); DSSetScrollRgn(dPtr,ktRect);/* Set scroll region x/ 
LineToCtmp2 * 2 + 1,tmp2); if (cPtrcontrlHilite != 255 &&/* Check if show it */ 
LineToCtmp1,0); cPtr->contr1Max != сРіг-› сопіг1Міп) ( 
DSCalcThumb(dPtr,cPtr); /% Re-calculate thumb */ 
ClosePoly(); /* Close the poly handle */ ForeColor(Clong)(blackColor));/* Маке it’s b&w  */ 
BackColor((Clong)CwhiteColor)); 
if CdPtr->up) /* Check if old poly hdl */ DSF i11Body(&tRect); /* Fill in scroll bar x/ 
KillPolyCdPtr- up); /* Release this poly hdl */ tRect = dPtr->cThumb; /* Set thumb rect area — */ 
dPtr-?up = рна]; /* Set up poly handle  */ DSFrameThumb(&tRect ); /* Frame thumb */ 
/* Create down poly hdl */ InsetRect(ktRect,1,1); /* Inset by one pixel %/ 
if (pHdl] = OpenPoly()) ( /* Check if got poly hdl */ DSFillThumbC&tRect); /* Clear inside of thumb */ 
16 CdPtr-»hFactor) ( /* Check horz position — */ ) 
MoveToCtmp2, tmp 1); else /* Nope, don’t want it */ 
LineToC@,tmp2 * 2 + 1); DSClearBody(&tRect); /* Clr scroll region x/ 
LineToC£, 1); ) 
LineToCtmp2, tmp 1); 
Of fsetPolyCpHdl,hBLen, 8); void DSPositionThumb(dPtr, cHd1, pt) 
DSPTR dPtr; /* Dual control pointer */ 
else ( /* Nope, vert position */ ControlHandle сНа1; /* Control handle x/ 
MoveToC 1,0); Point pt; /* Pt position of thumb */ 
LineToCtmp2 * 2 * 1,0); ( 
LineToCtmp 1, tmp 12; double offset; /* Working value offset */ 
LineToC 1,0); 
Of fsetPolyCpHd1,,hBLen); if (dPtr-— hFactor) /* Check if horizontal  */ 
) offset = pt.h; /* Use horizontal offset */ 
ClosePolyO; /* Close the poly handle */ else /* Nope, it's vertical  */ 
) offset = pt.v; /* Use vertical offset  */ 
1f (dPtr- down) /* Check if old poly hdl */ offset = offset / dPtr->tFactor; /* Reset ctr] value */ 
KillPolyCdPtr-»down?; /* Release this poly hdl */ C*cHdl12-»contrlValue += offset; 
dPtr->down = pHdl; /* Set down poly handle */ ИНИ /* Draw да thumb, again! */ 
void DSCalcThumb(dPtr,cPtr) void DSSetupThumbCdPtr , thumbP tr ) 
DSPTR dPtr; /* Dual control pointer */ DSPTR dP tr; /* Dual control pointer */ 
ControlPtr cPtr; /* Control pointer x/ шаш thumbPtr; /* Thumb’s info pointer */ 
double tmp 1, tmp2; /* Working tmp registers */ Point msePt; /* Working mouse point %/ 
short offset; /* Working pixel offset */ 
Rect wRect; /* Working scroll area  */ msePt.h = thumbPtr->limitRect. left; /* Save mse down */ 
msePt.v = thumbPtr-»limitRect. top; 
/* Make sure this is min */ DSSetScrollRgnCdPtr , &thumbPtr-> limitRect); /*Set limt*/ 
cPtr-»contrlMin = minCcPtr-contrlMin, cPtr->contr Max); if (dPtr->hFactor) ( /* Check if horz scroll */ 


/* Adjust it for mse %/ 
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thumbPtr-> limitRect.left += msePt.h - dPtr->cThumb. left; Of fsetRectC&bRect, (*dPtr->cHdl )->»contriRect. left, 


thumbPtr-»limitRect.right -= dPtr-»cThumb.right - msePt.h - 1; (*gPtr-»cHd12-»contrlRect.top?); 

/* Set slop rect area x/ DSClearBody(&bRect ); /* Clear the body part  */ 
thumbPtr->slopRect.top = thumbPtr-»limitRect.top - 16; DSFrameBody(&bRect ); /* Frame high button box */ 
thumbPtr-»slopRect.bottom = thumbPtr-»limitRect.bottom + /* Set low button offset */ 

16; offset = dPtr->sLen - dPtr->bLen - 1; 
thumbPtr->slopRect. left = -32000; Of fsetRect(&bRect,dPtr->hFactor * offset, 
thumbPtr->slopRect.right = 32000; dPtr->vFactor * offset); 
thumbPtr-^axis = hAxisOnly; /* Set axis dragging dir*/ DSClearBody(&bRect); /* Clear the body part %/ 

DSFrameBody(&bRect); /* Frame low button box */ 
else ( /* Nope, vert scroll bar*/ ) 

/* Adjust it for mse х/ 
thumbPtr-»limitRect.top += msePt.v - dPtr->cThumb. top; long DSTestControl(dPtr, pt) 
thumbPtr-»limitRect.bottom -= dPtr->cThumb.bottom - msePt.v DSPTR dPtr; /* Dual control pointer */ 

mp Point pt; /* Point position ж/ 

/* Set slop rect area */ ( 
thumbPtr->slopRect. left = thumbPtr->limitRect.left - 16; Rect cRect; /* Working control rect */ 
thumbPtr-»slopRect.right = thumbPtr->limitRect.right + 16; Rect tRect; /* Working temp rect area*/ 
thumbPtr->slopRect. top = -32000; Rect bRect; /* Working button rect  */ 
thumbPtr->slopRect .bottom = 32000; short offset; /* Working offset */ 
thumbPtr-»axis = vAxisOnly; /* Set axis dragging dir*/ short point; /* Working pt in region */ 

long status = 0; /* Working status flag  */ 

cRect = (*dPtr-»cHdl2— contrlRect;/* Set ctrl rect */ 
void DSDrawHBtnCdPtr,btn,f i11) bRect = dPtr-> thumb; /* Set button rect area */ 
if (dPtr->hFactor) /* Check if horz button */ 

DSPTR oP tr; /* Dual control pointer */ bRect.right = dPtr->hBLen; /* Adjust for horz button*/ 

PolyHandle btn; /* Poly button handle x/ else 

short fill; /* Fill flag indicator */ bRect.bottom = dPtr->hBLen; /* Adjust for vert buttn*/ 

tRect = bRect; /* Set the temp rect area*/ 
( Of fsetRect(&tRect, cRect. lef t,cRect . top); 
/* Offset where button  */ і? (PtInRect(pt,&tRect)) ( /* Check if high up buttn*/ 
OffsetPolyCbtn, C*dPtr-»cHdl10-»contrlRect.left + 1, status = inUpButton; /* Set high up button x/ 
C*dPtr-?cHdlo-»contrlRect.top + 1); dPtr-»altButton = FALSE; /* Not using alt button */ 
if (fill) /* Check if filling arrow*/ ) 
DSFillArrow(btn); /* Fill in arrow button */ if (!status) ( /* Check if prev part */ 
else /* Nope, not clearing it */ /* Adjust for down button*/ 
DSClearArrow(btn); /* Clear the arrow button*/ OffsetRect(&tRect,dPtr->hFactor * dPtr->hBLen, 
DSFrameArrowCbtn); /* Frame the arrow button*/ dPtr-?vFactor * dPtr-»hBLen); 
/* Restore the button — */ if (PtInRect(pt,&tRect)) (/* Check if high down */ 
Of fsetPolyCbtn, -C*dPtr-»cHdl12-»contrlRect. left - 1, status = inDownButton; /% Set high down button */ 
-C*dPtr-?cHdl2-»contrlRect.top - 1); dPtr-»altButton = FALSE; /% Not using alt button  */ 

) y 

void DSDrawLBtnCdPtr ,btn,f 111) if (!status) ( /* Check if prev part х/ 

DSPTR dPtr; /* Dual control pointer */ tRect = bRect; /* Set the temp rect area*/ 

PoluHandle btn; /* Polu button handle x/ offset = dPtr->sLen - dPtr->bLen; 

short fill; /* Fill flag indicator  */ /* Offset where low up */ 

( OffsetRect(&tRect,cRect.left + dPtr— hFactor*offset, 
short tmp1, tmp2; /* Working tmp variables */ cRect.top + dPtr->vFactor*offset); 
short offset; /* Working offset */ if (PtInRect(pt,&tRect)) (/* Check if low up button*/ 
status = inUpButton; /* Set low up button x/ 
offset = dPtr->sLen - dPtr—bLen - 1;/* Set offset */ dPtr-»altButton = TRUE; /* Using alt button х/ 
/* Offset where button */ ) 
OffsetPolyCbtn, tmp1 = C*dPtr->cHdl)->contrlRect. left + 
dPtr->hFactor * offset + 1,tmp2 = C*dPtr-»cHdl2- if (!status) ( /* Check if prev part */ 
ycontrlRect.top + dPtr->vFactor * offset + 1); /* Offset where low down */ 
if (fill) /* Check if filling arrow */ OffsetRect(&tRect,dPtr-»hFactor * dPtr->hBLen, 
DSFillArrow(btn); /* Fill in arrow button */ dPtr->vFactor * dPtr-»hBLen); 
else /* Nope, not clearing it */ if (PtInRect(pt,&tRect)) (/* Check if the low down */ 
DSClearArrow(btn); /* Clear the arrow button */ status = inDownButton; /* Set low down button x/ 
DSFrameArrow(btn); /* Frame the arrow button */ dPtr-»altButton = TRUE; /* Using alt button */ 
Of fsetPoly(btn,-tmp1,-tmp2);/* Restore the button — */ ) 

) 

void DSFrameButtons(dPtr ) if C!status) { /* Check if prev part х/ 

DSPTR dPtr; /* Dual control pointer %/ if (PtInRect(pt,&dPtr->cThumb))/* Check if thumb */ 

( status = inThumb; /* Set thumb part */ 

Rect bRect; /* Working box rect area */ 

short offset; /* Working low button х/ if (!status) ( /* Check if prev part d 
/* Set relative point | */ 

bRect.left = bRect.top = 0;/* Setup rect area x/ point = pt.h * dPtr—hFactor + pt.v * dPtr->vFactor; 

bRect.right = bRect.bottom = аРіг-› беп + 1; /* Set relative offset */ 

/* Offset high button box*/ offset = dPtr->cThumb. left * dPtr->hFactor + 


220 © The Best of MacTutor, Vol. 5 


dPtr->cThumb.top * dPtr->vFactor; 
1f (point > offset) 
status = inPageDown; 
else 
status = inPageUp; 


/* Set down page region 


/* Set up page region 


return(status); /* Return status part 


DSSetScrollRgn(dPtr,scrollRgn) 
DSPTR dPtr; /* Dual control pointer 
Rect *scrollRgn; /* Scrolling region area 


*scrollRgn = C*dPtr-—cHdl2-»contrlRect;/* Set area 
InsetRectCscrollRgn, 1, 1); /* Shrink it a bit 

1f (dPtr—hFactor) ( 
scrollRgn- left += dPtr->bLen; /* Adjust rect area 
ScrollRgno right -= dPtr->bLen; 


else ( 
scrollRgn-— top += dPtr-?bLen;/* Adjust rect area 
scrollRgn- bottom -= dPtr-»bLen; 


) 


void DSGetBackGround(Ccolor) 
RGBColor *color; ( GetBackColor(color); ) 
void DSGetForeGround(color) 
RGBColor *color; ( GetForeColor(color); ) 
void DSSe tBackGround(color ) 
RGBColor *color; { RGBBackColor(color); } 
void DSSetForeGround(color) 
RGBColor *color; { RGBForeColor(color); } 


void DSEraseRect(rect) 
Rect *rect; ( EraseRect(rect); ) 
void DSFrameRect(rect) 


/* Check if in down page */ 


*/ 
*/ 
*/ 


*/ 
х/ 


*/ 


* 


/* Check if horizontal bar*/ 


*/ 


/* It’s a vert scroll bar */ 


i 


ControlHandle cHd1; 


Rect *rect; ( FrameRect(rect); } 
void DSF il IRect(rect, pattern) 

Rect *rect; Pattern *pattern; (FillRect(rect,pattern);) 
void DSErasePolu(polu) 

PoluHandle poly; ( ErasePoly(poly); ) 
void DSFramePolu(polu) 

PolyHandle poly; ( FramePolu(polu); ) 
void DSFillPolyCpoly,pattern) 

PolyHandle poly; Pattern *pattern; 

( FillPolyCpoly,pattern); ) 


void DSDrawOb jectCcHdl, getGround, setGround, 


објесі, со1ог,агді, аг92) 
/* Control handle x/ 


ProcPtr ge tGround; /* Get back/fore grd proc*/ 
ProcPtr setGround; /* Set back/fore grd proc*/ 
ProcPtr object; /* Draw object proc х/ 
short color; /* Color index */ 
(279 агд1,агд2; /* Argument’s parameters */ 
AuxCt]Hnd] | acHd] = NIL; /% Working aux color hdl */ 
RGBColor oldColor; /* Working old color x / 
RGBColor newColor; /* Working new color х/ 


/* Check if has color */ 

їе CC*CCDSHDL )(¢*cHd1 )-> contr 1Data)))-»hasColor) ( 
GetAuxCtlCcHdl,&acHd1); /% Get control color info*/ 
if (acHdl) ( /* Check if really got it*/ 
(*getGround)(&oldColor); /* Get back-ground color */ 
/* Get object’s color x / 
newColor =(*(*acHd1 )-› acCTable)-»ctTable[color].rgb; 
(*setGround)(&newColor); /* Set control obj color */ 


) 
(*objectCarg1,arg2); 


/* Draw the object х/ 
if (acHdl) 


/* Check if have aux hdl */ 


(*setGround)(&oldColor); /% Restore back-grd color*/ Е 


© The Best of MacTutor, Vol. 5 


221 


Jórg's Folder 
Apple's C++ 


“C++” 

OOPS has taken its literal meaning with the brief C++ 
introduction that I wrote 2 months ago... now that I have a 
compiler to test the examples that I thought up. Of course, I did 
itall wrong. Seasoned C++ experts might have smiled when they 
read my ‘matrix class’ definitions, others (like myself) might not 
have noticed the goofups at all. Anyway, this month you'll find 
much more detailed examples of the same kind, and I can assure 
you they work, because they've been tested. [Before you cancel 
your subscription in panic, let me emphasize that the overview of 
C++ in the same article is still basically correct]. 

Someone on the networks came up with this quote: “C++ is 
the Forth of the 90' s - they don’t call it ‘uh-oh programming’ for 
nothing" . Well, I can confirm on the uh-oh part, and as far as the 
Forth is concerned, at least I’m learning this language as much by 
trial and error as I did with Forth. So let's follow the learning 
curve together; maybe that is not such a bad approach for a 
tutorial. 

Our example is an MPW tool that does some array compu- 
tations using a matrix and vector class that have a number of 
methods defined. We'll go through the example step by step, and 
learn some important features of data structure definition in C++. 
The program is not Mac-specific; it uses only the standard C++ 
libraries, so you can check out the examples on a UNIX machine 
with C++ even if you don't have access to Apple's C++ (and if 
you do, chances are that you might not need this tutorial at all). 


Simple I/O in C++ 
The first few lines of our example - after the #includes - 
define a simple error message function which writes a string to 
standard error and exits the program. The definition looks very 
much like C except for the line 


cerr << p << endl; I | 
which is a C++ I/Ó statement that writes the string p to 


standard error. cerr is an object of class ostream which is 
basically an output file; cerr is predefined to be the standard error 
Output for a UNIX system or for MPW. Likewise, cin and cout 
are predefined standard input and output (console). << is the 
output operator, and to write an object x to standard output you 
simply write 

cout «« x; 

Whether the compiler will accept this statement or not 
depends whether the operator << has been defined for the type x. 
Standard definitions for most simple types are contained in the 
header file Stream.h. The operator >> is the input operator: 

cin > i; 

would read the int i from standard input. endl is used to flush 
the output buffer (otherwise the actual output might appear on the 
screen at a later time), and add an end-of-line. 
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The Vector Class 

In the following, we define a class vector, a resizeable one- 
dimensional array of float with optional range checking. Its 
private variables are float* v, which will be used as a pointer to 
the data, and int sz, the number of elements in the vector. 

We then declare the class matrix (defined further down) as 
a friend of vector. Why this? Later, we will define an operator 
which multiplies a matrix with a vector as a method of the class 
matrix. This operator needs access to the data contained in the 
vector. Since the normal way of accessing involves bounds 
checking and is therefore slow, we want to be able to access the 
*private part' v of the vector directly. Friends of a class may do 
this. 

The publicly accessible parts of the class are all the methods 
defined for our vector: 

• the constructors, vector(int) and vector(vector&); the first 
one creates a new vector given its size as an argument, the second 
one duplicates an existing vector by creating a new one of the 
same size and copying all the elements; 

• the destructor, ~vector(), which will free the space allo- 
cated to the object’s data when the object is no longer needed; 

° size(), an inline function that returns the length of the 
vector; 

° set_size(int), which changes the size of an existing vector; 

° the indexing operator [], for accessing an element of the 
vector. We have to note here that the operator returns a reference 
toa float, nota float value, so that an indexed element can be used 
on both sides of an assignment statement. [] will check the index 
against the bounds of the vector; 

* elem(int i), an inline function which returns the value of the 
i-th element of the vector without range checking, for fast access; 

° the operators =, +, and -, which are used for assignment and 
elementwise addition or subtraction of vectors. They will check 
whether the vectors on both sides of the operator sign are of equal 
size, perform the operation, and return the reference to a newly 
created vector which contains the result; 

* the operator *, which computes the scalar product of two 
vectors, and returns a float value; 

° print(), which prints out the contents of the vector to cout. 

The class definition constitutes the interface to the object's 
structure and its methods; the actual implementation follows. 

I have put informative messages into the constructor and 
destructor methods so that one can see how new objects are 
created and released. This is important for debugging; if less 
objects are released than created, something might have gone 
wrong, and at least one has wasted memory space. 

vector(size) creates an array of floats on the heap that is size 
elements long. vector(a), where a is another vector, will create a 
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new vector which is an exact copy of a. These constructors are 
called when new vectors are defined: 
vector x(5); // calls vector(int) 


vector y = x; // calls vector(vector&) e 
In the for statement you see another characteristic feature of 


C++: declarations can be made any where, so the loop index i may 
be declared as a register variable just for the scope of the loop. 

The destructor ~vector() is called when an instance of vector 
goes ‘out of scope’, and deletes the space allocated for the array 
v before the object itself is deleted. Defining a destructor is 
usually done when you have allocated some of your own memory 
on construction, just as we did. 

The operator [] will first see if the index is within the limits 
of the array and abort with an error message if not (this could be 
done in a more sophisticated way); then it indexes the private 
array v and returns a reference to its i-th element. Note that the 
operator [], when used with v, will be the usual array indexing 
function; when used on a vector, it uses range checking, since its 
original definition has been overloaded. If we define a function 
or an operator with the same name as an existing one, old 
definitions will automatically be overloaded in C++ 2.0; the 
overload statement of the previous version described in Strous- 
trup's book is not necessary anymore. 

The assignment operator will copy all elements of the 
argument vector into its parent vector, making sure that both are 
of the same size. It returns a reference to the argument vector, so 
that multiple assignment statements are possible: 

a = b = c; // copies c into b and a 

+ and - create a new vector of the same size as of its 
arguments and copies the sum of the two vectors into it. The new 
vector is allocated on the heap, using the new operator: 


vector& c = *new vector(sz); | 
thatis,we defineareference c to a vector,to which we assign 


the pointer to the new vector. One could think that one could 
simply create a new instance by writing 


vector c(sz); | . 
however, this will only create a local instance of vector, 


which will be deleted as soon as the function is left. The compiler, 
by the way, complains if you use a local object as the return value 
(Just as a warning, it will still compile...). Rightly so, since local 
objects are allocated in a local stack frame, and disappear as soon 
as that stack frame is UNLKed and the JSR called. 

Therefore, we must create a new vector in the hcap which 
will hold the result of the addition or subtraction. This will later 
require some housekeeping on our part, because a heap object is 
not automatically deleted when its scope is left. We must take 
care of that ourselves (see below). 

The definition of the scalar product, *, and the print() 
function should now be self-explanatory. I have not given a 
definition for the resizing function, set. size(int); try whether you 
can come up with a definition for it. 


The Matrix Class 
Contrary to what I wrote in the September column, we won't 
define matrix as a class derived from vector. Also, we won't 
define matrix as an array of vectors; I had tried this approach, 
which is very elegant when it works, but screwed up so com- 
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pletely that I haven't come up with a solution as the deadline is 
approaching. Therefore, we'll use a simpler definition, which has 
the advantage of being faster than what I thought up before. 

Thus: class matrix has the private variables mv, a pointer to 
an array of floats, and the two integers rows and cols, which 
indicate the number of rows and columns in the array. We will do 
our index calculations explicitly in the methods of matrix and use 
one-dimensional indexing for actually accessing the elements of 
mv within the method. To the outside, this is not visible and we'll 
always use two-dimensional indexing with range checking. 

The methods defined are: 

* constructors and a destructor, analogous to those of class 
vector; 

* (wo functions that return the number of rows and columns 
of the matrix (note that rowsize should not be read as ‘size of one 
row’, but ‘size in units of rows’); 

° Set size, unimplemented as for vector, left for you as an 
exercise; 

* the two-dimensional indexing operator (), which takes two 
ints i,j as arguments and returns a reference to the (i,j)-th element. 
Thus, we won't use square brackets for indexing: instead of 
a[i][j] like in C we'll write a(i,j) like in Fortran. This is an 
overload of the function call operator () which was not possible 
in version 1 of C++, but is legal in C++ 2.0. Any operator may be 
redefined in C++ 2.0, including the comma. 

* the quick indexing function elem(i,j), which returns the 
value of the (i,j)-th element without bounds checking; 

* the assignment, addition and subtraction operators, which 
work analogously to those for vectors; 

* two multiplication operators, one for multiplying two 
matrices, one for multiplying a vector by a matrix from the left; 

* the print() function. 


The method definitions follow the class declaration, and you 
should now be able to go through them without much explana- 
tion. The matrix* vector operator accesses the data of the vector 
argument a directly (a.v[j]); it is for this reason that we made 
matrix a friend of vector. We could have achieved the same 
result without the friend declaration by using the inline indexing 
function a.elem(j), but the inline expansion of function is not 
guaranteed in all implementations. 


The Main Program 

Using matrix operations in the main program has now 

become very simple and easy to read. For instance, the statement 
matrix& x = a*c; 

will compute the matrix product of a and c (given that the 
dimensions are correct such that the product can be computed), 
put the result into a new matrix allocated on the heap and make 
the reference x point to that matrix. From now on, x can be used 
whenever an object of type matrix is required; x.print(), for 
instance, prints the contents of x. The only thing that we have to 
be careful about is to delete all ‘hidden instances’ explicitly at the 
end of the block in which they have been created: 


delete &x; delete &f; I | 
The compiler will also issue warnings here, presumably 
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because x and f might not be references to heap objects, and the 
delete statements might crash at run time. 

More complicated statements like 

matrix& x = (а + b)*c; 

might leave intermediate results on the heap to which there 
Is no more access. Some sort of a garbage collector would be 
needed to clean up those objects; I don't know whether some- 
thing is planned in that direction. For the time being, you can 
always break up such lines into multiple statements and assign 
any intermediate result explicitly to a reference variable, which 
can be deleted later. 

Ifyourun the example - and we include the MPW tool on the 
source code disk for those who have no C++ compiler available 
- you’ll notice how instances of vectors and matrices are created 
and deleted, and how the product matrix A*C automatically 
comes out the correct size. 

In the future, I am planning to implement a whole library of 
matrix functions in C++; maybe we’ll have a follow-up on this 
article some time. In the next part of the tutorial, we'll deal with 
Mac-style programming, we'll define a simple application class 
with an event loop and event handlers. 


Apple's C++ 

Although I haven't covered Macintosh-specific details this 
month, let me just mention the fact that the examples given here 
were compiled using a test version of the Apple MPW C++ 
compiler. This compiler is based upon the AT&T C++ Language 
System, which is a pre-compiler that generates C code from a 
C++ source. The C code can then be compiled into machine code 
by any C compiler. This strategy was taken so that the C++ 
system could be quickly implemented on any machine running C. 

The actual version of AT&T C++ is 2.0, and deviates from 
the description in Bjarne Stroustrup's book. А number of features 
have been added, which I have partially covered already. As we 
encounter them in the course of these tutorials, we'll learn more 
about the changes in C++ 2.0 with respect to the book. 


Feedback dept. 

"Dear Jórg, 

Thank you for your interesting article on compilers in 
August MacTutor. I feel very little attention has been paid to the 
quality of the code produced by Mac compilers. I have been 
porting some FORTRAN code using LSF 1.2 to the MacII and 
have been very embarrassed by IBM'ers when comparing execu- 
tion speed on their 16MHz 386 machines - due purely to the much 
better optimization of MS-DOS FORTRAN compilers [Having 
used Lahey Fortran 77 on a286 machine, I can only agree with 
you - ji]. 

I was also very disappointed when Apple released MPW 3.0 
to find that their C compiler produced code significantly slower 
than the old 2.0 C compiler from Green Hills. For example the old 
2.0 compiler ran your benchmarks (as written) in 3.8 (non opt) 
and 2.8 (opt) secs respectively. Using pointers instead of index- 
ing in the inner loop reduced that to 2.46 secs. Happily one can 
use the 2.0 compiler as a tool under 3.0 for those time critical 
routines and mix 2.0 and 3.0 object code as long as you follow 
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certain rules /Summarize those rules for us and write us about it, 
this is interesting - jl]. 

I suppose you have had your attention drawn to the bugs in 
the C code, but just in case...... 

° C arrays index from 0 so you were overwriting memory 
when addressing index[50][50] in your C routine! 

[True! What shall I say except the remarks about learning 
curves that I made in the beginning......] 

* C and Pascal arrays are reversed as compared to FOR- 
TRAN. ie. A(20,30) in FORTRAN should be declared 
A[30][20] in C. It follows from this that for correct addressing the 
arrays in the C parameter list should be declared a[][50], not 
а(501П. I found that if you correct this then the C non-pointer 
routines are significantly slowed down even more! 

Andrew Cunningham, Mona Vale, NSW, Australia" 

[The historical reason for the unsatisfactory optimization of 
most Macintosh compilers is probably that in the beginning most 
people were so glad to have any compiler at all that they did not 
pay much attention to the quality of the code as long as the stuff 
ran at all. Also, the toolbox calls are always the same, so it 
doesn't really matter whether your code is well-optimized or not 
as long as you mainly use toolbox calls and not doing any 
involved computations. Hopefully, the impact of the Macll in the 
scientificlengineering sector is strong enough to create some 
pressure on compiler writers to provide optimal tools - jl] 


On the network: 

Date: Fri, 8 Sep 89 10:18:24 CDT 

From: “Bob Loewenstein” <rfl@oddjob.uchicago.edu> 
To: Langowski%frembI5 1 .bitnet@ tank.uchicago.edu 
Subject: Neon 


I talked briefly with Kriya and it looks like they will put it 
into the public domain shortly. 


Bob 
[Very good! We're all looking forward to it!] 


See you again next month. 


Listing 1: Matrix operations in C++ 


Sinclude <String.h> 
include «Stream.h» 
include «StdLib.h» 


void error (char* p) 


cerr << p << endl; 
exitC1); 


class vector 


float* v; 
int sz; 
friend matrix; 


public: 


vector (int); 
vector(vector&); 
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“vector(); 

int size () ( return sz; ) 

void set_size(int); 

float& operator []Cint); 

float elemCint i) ( return v[i); ) 

vector& operator- (vector&); // assignment 
float operator* Cvector&); // scalar product 


vector& operator* Cvector&); // elementwise addition 
vector& operator- Cvector&); // and subtraction 


void print(); 
); 
vector::vector Cint size) 


cout << “constructing vector object” << endl; 
if Csize<=8) 
( v = 0; return; } 
62 = size; 
v = new float{sz]; 


vector: :vector (vector& a) 


cout << “copying vector object” << endl; 

sz = 8.52; 

v = new float[sz]; 

for (register int 1=0 ; i«sz ; i++) 
vli] = a.vflil; 


vector: :~vector (С) 


cout << “deleting vector object” << endl; 
delete v; 


floats 
vector: :operator(] Cint i) 


if Ci«0 || i= sz) 
error(*class vector: index out of range”); 
return v[i); 


vector& 
(o OU La (vector& a) 


if (a.sz != 52) 

error(^class vector: size mismatch in =”); 
for (register int 1=0 ; i<sz ; ін) 

vli] = a.vlil; 
return a; 


vector& 
vector::operator* Cvector& а) 


if (sz != a.sz) 
error(“class vector: size mismatch in +“); 
vector& c = *new vector(sz); 
// DON'T USE vector с(62); 


// this would be destroyed on exiting the method 


for (register int i-0 ; i«sz ; i**) 
c.v[i] = vlilta.vlil; 
return c; 


vector& 
vector::operator- Cvector& a) 
if (sz != a.sz) 


error(“class vector: size mismatch in +”); 
vector& c = *new vector(sz); 
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for (register int i-0 ; i«sz ; i++) 
c.vlil = vlil-a.vlil; 
return c; 


float 
vector::operator* (vector& a) 


if (sz != a.sz) 
error(“class vector: size mismatch in *^); 
float sum = 0; 
for (register int i=0 ; i«sz ; i++) 
sum = sum + v[il*a.v[il; 
return sum; 


) 


void 
vector::print() 


for (int i=0; i«sz-1; i++) 
cout << v[i] << “ | 4 
cout << v[sz-1] << end]; 


class matrix 


float* mv; 
int rows, cols; 


public: 
matrixCint, int); 
matrixCmatr ix&); 
“matrix ); 
int rowsize () ( return rows; ) 
int colsize (С) ( return cols; ) 
void set. sizeCint, int); 
float& operator (OCint, int); 


float elenCint i, int j) ( return nv[i*cols + j]; ) 


matrix& operator- (matrix&); // assignment 


matrix& operator+ (matrix&); // elementwise addition 
matrix& operator- (matrix&); // elementwise subtraction 


matrix& operator* (matrix&); // matrix product 
vector& operator* (vector&); // matrix*vector 


void print); 


matrix::matrix Cint rowsz, int colsz) 


cout << “constructing matrix object” << endl; 


if (rowsz ‹=0 || colsz ‹=0) 
( mv = 0; return; ) 

rows = rOWSZ; 

cols = colsz; 

mv = new float[rows*cols]; 


) 


matrix::matrix (matrix& a) 


cout << “copying matrix object” << endl; 

rows = &.rows; cols = a.cols; 

int size = rows*cols; 

mv = new float{size]; 

for (register int i=0 ; i<size ; 1++) 
mv[i] = a.mv[il; 


matrix: :~matrix (©) 
cout << “deleting matrix object” << endl; 


delete mv; 


f loat& 
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matrix::operator() Cint i, int j) 


if Сі‹0 || i= rows) 

error(^class matrix: column index out of range”); 
if С]‹0 || ј›= cols) 

error(“class matrix: row index out of range”); 
return mv[i*cols + j); 


matr ix& 
matrix: :operator= (matrix& a) 


1f (Ca.rows != rows) || Ca.cols != cols)) 


error(*class matrix: size mismatch in assignment”); 


for (register int i-0 ; i«rows*cols ; i++) 
nv[i] = a.mvlil; 
return a; 


matrix& 
matrix::operator* Cmatrix& a) 


if (Crows != a.rows) || (cols != a.cols)) 
error(“class matrix: size mismatch in +”); 

matrix& c = *new matrix(rows,cols); 

for (register int 1=0 ; i«rows*cols ; 1++) 
c.mv[i] = mvlilta.mvlil; 

return c; 


matr ix& 
matrix: :operator- (matrix& а) 


if (Crows != a.rows) || (cols != a.cols)) 
error(*class matrix: size mismatch in +”); 

matrix& c = “пен matrix(Crows,cols); 

for (register int i=0 ; i<rows*cols ; i++) 
c.mv[i] = ту[1]-а.ту[1], 

return c; 


matr ix& 
matrix: :operator* (matrix& а) 


1f (cols != a.rows) 

error(*class matrix: size mismatch in *"); 
matrix& с = “пен matrix(rows,a.cols); 
for (register int i-0 ; i«rows; 1++) 

for (register int ј=0 ; j«a.cols; ј++) 


register float sum = 0; 
for (register int k=0 ; k«cols; k**) 


sum = sum + elemCi,k2*a.elemCk,j2; // elem is faster 


cCi,j) = sum; 


return c; 


vector& 
matrix::operator* (vector& a) 


1f (cols != a.sz) 
error(^class matrix: size mismatch in *vector"); 

vector& c = “пен vector(rows); 
for (register int i-0 ; i«rows; it+) 

register float sum = 0; 

for (register int j=0 ; j<cols; j++) 

sum = sum + elemCi, j)*a.v[j]; 
c[i] = sum; 


return c; 
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void 
matrix::print() 


for Cint i=0; i«rows; 1++) 
for (int ј=0; j<cols-1; j++) 


cout << elem(i,j) << * | *; 
cout << elem(i,cols-1) << endl; 


) 


int 

mainCint argc, char* argv[]) 
cout << “Start main program...” << endl; 
int i,j; 
cout << “Defining A and C^ << endl; 
matrix 8(3,5); 
matrix c(5,3); 


for (i20; 1‹3; із) 
Co 165; jtt) 
aci,j) 
cCGj, i2 


i + (1.0*j)/10; 
асі, ј) - 2; 


cout << “Assigning B“ << endl; 
matrix b = a; 


cout << “Elements of A:” << endl; 
a.printd); 


cout << “Elements of B:^ << endl; 
b.print(); 


` cout << “Elements of C:” << endl; 
c.printC; 


//cout << “Defining X^ << endl; 
// matrix x(3,3); 


cout << “Multiplying A*C into X^ << endl; 
matrixk x = ас; 


cout << “Elements of A*C:" << endl; 
x.printd); 


cout << “Defining D^ << endl; 
vector d(3); 
for (i20; 143; i++) 

d[i] = i*2.75; 
cout << “Defining E^ << endl; 
vector e = d; 


cout << “Multiplying C*E into F^ << endl; 
vector& f = c*e; 


cout << “Elements of D, E, Ғ:” << endl; 
d.print(2; e.printQ); f.printd); 


aC 1,4) = 432.056; 
b= a; 

a.printQ); b.printd); 
delete &x; delete &f; 


cout << “Exiting” << endl; 
return 0; 


© The Best of MacTutor, Vol. 5 


Intermediate Mac'ing 
AppleTalk Chatter Box 


A Chat Program for AppleTalk 

(Rob Hafernik has been programming at one job or another 
for 10 years. Over the years, he's been involved in a wide variety 
of programming projects; working with banks, hospitals, the 
Space Shuttle, robotics, graphics, and so on. He' sfinally lucked 
out and now actually gets paid to program the Macintosh for 
Technology Works in Austin, Texas. He can be reached via e- 
mail on BIX or MacNet as user ID "rob42" ) 

From the first time I sat down to a Mac connected to 
AppleTalk, I wanted to write a program to let users on Ap- 
pleTalk-connected Macs chat back and forth. The idea lan- 
guished in the back of my mind for years until I recently found 
myself with a need to learn AppleTalk and a whole day free of 
other programming responsibilities. Thus Chatterbox was be- 
gun. 
I had already spent a couple of hours studying Inside 
AppleTalk to get a feel for the various AppleTalk protocols and 
more time pouring over the various Inside Macintosh chapters 
that cover AppleTalk. From the start, I'd decided that the 
program would not be restricted to just two users talking back and 
forth. The program‘had to be able to let any user send a message 
toany subsetof therest of the userson the internet (orall of them). 
I also wanted to keep the program as simple and fool-proof as 
possible. From all of this I came to the decision that Chatterbox 
would use the Name Binding Protocol (NBP) to see who was 
available to talk to and the Datagram Delivery Protocol (DDP) to 
send and receive the actual messages. 


AppleTalk Basics 

Firstafew AppleTalk terms. Each device (such as your Mac 
or LaserWriter) on an AppleTalk network is called a node. Up to 
32 devices can be connected together to form an AppleTalk 
network (up to 255 devices are allowed with Apple's new release 
of AppleTalk). Several networks may be connected together (via 
special nodes called internet routers) to form a zone. The sum of 
all of the networks connected together are referred to as an 
internet. Aseach device boots up, it establishes contact with its 
network and comes up with a unique node id. Since more than 
one program may be running on a given node that wants to use 
the network, an addressing mechanism called sockets allows 
each node to have up to 254 separate addressable entities running 
at any one time. The low numbered sockets are reserved by 
Apple for the low-level protocols (such as the Name Binding 
Protocol we'll discuss below), but sockets 128-254 are open for 
use by any Mac program. Each socket must have a socket 
listener. This is a piece of code that the DDP calls to handle 
incoming messages. Apple supplies a default socket listener that 
does the minimum - it copies incoming messages to the buffer 
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you supply and sets a result field. 

The Datagram Delivery Protocol is the simplest data transfer 
protocol of them all and the one that all of the higher-level 
protocols are based on: it doesn't guarantee delivery and it 
doesn’t guarantee that packets will arrive intact. What does it do? 
Well, it provides for the “best effort” delivery of a packet of up 
to 586 bytes to a given network, node and socket on the internet. 
What more could a chat program ask for? One note: throughout 
this program I have used the “alternate interface”, as opposed to 
the “preferred interface”. The “preferred interface” (described in 
Inside Macintosh Volume V) is based on the same type of 
parameter-block calls as the low-level file system interface. 
Unfortunately, since the “preferred interface” provides no 
equivalent of the “DDPRead” function, a socket listener and read 
function must be provided by the programmer. For this simple | 
application, the “alternate interface" proved best and easiest to 
understand. 

The Name Binding Protocol provides a way for programs 
that will use AppleTalk (client programs) to register on the 
network. Each client program opens a socket, then registers a 
name and type with the NBP. A client program can also ask NBP 
for the names, types, and addresses of other clients in its zone. 
NBP provides a wild-card match scheme that allows, for ex- 
ample, aclienttoscan the zone for all other names of a given type. 
This is the mechanism that Chatterbox uses to find other users to 
talk to. 


The Chatterbox Program 

Now let's look at the program. When Chatterbox first starts 
up, itasks the user for the name they wish to use during the session 
(figure 1). The name defaults to the Chooser name, but the user 
may override this and provide any name less than 32 characters 
long (the limit allowed by the NBP). After that, the program 
displays a window with several parts (figure 2). There is a 
scrollable area where the names of other Chatterbox users are 
displayed; an area for status messages (I like programs that let me 
know what they’re doing, especially ones like this whose actions 
are mostly invisible); a TextEdit field for messages you wish to 
send; and a read-only TextEdit field where incoming messages 


Enter the name you want to go by: 


Figure 1 
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Hark К Listening... 
FE 


Type a message, «return» to send: 


Received Messages: 


Now is the time for al! good programmers (Rob) 

to come to the aid of the Macintoshes. (Rob) 
There was a young man from Nantucket... (Mark K) 
Hell, never mind... (Mark К) 

Hey, ! heard q good one the other day: (Rob) 

14 seems that there was this traveling - (Rob) 
salesman, who went to sell this farmer - (Rob) 

а tractor. Now this farmer had a daughter - (Rob) 


Figure 2 


are displayed. 

To use the program, the user selects recipients from the list. 
Multiple selections are allowed, both continuous selections 
made with a shift-click and discontinuous selections made with 
a command-click. Messages entered in the edit-text field are 
transmitted by hitting the <return> key at the end of the message. 
As others send messages, they’re displayed in the area at the 
bottom. As more messages come in, the old ones scroll up and 
are eventually deleted as they scroll off the top. 

The flow of the program is pretty simple. Once the usual 
Mac stuff is initialized, the program opens a socket that will be 
used to receive messages. To keep things easy, I used the default, 
Apple-supplied, socket listener. Then the RegisterName routine 
allocates a parameter block, fills in the user’s name, type, zone, 
socket and a few other parameters and calls NBPRegister to do 
the work. The zone string is set to “*”, meaning “this zone" and 
the type string to “Chatterbox”. By using the “*” zone name, 
Chatterbox is limiting communications to a single zone (the one 
it's in), but this simplifies the program considerably. Note that 
when the program quits, it must call NBPRemove to take this 
name out of the list - see the UnRegisterName routine. 

After registering on the internet, the next thing the program 
does is send out a special greeting to all other Chatterboxes. 
Why? Well, it's a long story. When I first wrote the program, I 
thought that it would periodically scan the zone for new users and 
add them to its display. This proved to be very cumbersome (it 
takes a second or two to do the lookup for one thing, a pretty big 
interruption if you're doing anything) and I went through several 
schemes before I came up with another method: as Chatterbox 
gets incoming messages, it looks to see if they begin with the non- 
breaking space (option-space from the keyboard). If so, it's a 
signal that the list of users in the zone has changed and it's time 
to call CheckForUsers (discussed below). This means that the 
user is only interrupted when a new user comes along (or goes 
away, we'll getto that later). So this special message that is sent 
out by a new Chatterbox coming along triggers all the other 
Chatterboxes to look around the zone for their fellows. Why go 
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toall the trouble of a CheckForUsers and not just add the new user 
to the list? In a word, redundancy. This may take a little extra ` 
processor time, but it guarantees that the list of users is up-to- 
date, regardless of the whims and crashes of the network. 

The CheckForUsers routine is a bit complicated. The 
current list of other Chatterboxes in the zone is displayed using 
the list manager. Whenever CheckForUsers scans the network 
for other users, it mnustadd new Chatterboxes to the list and delete 
Chatterboxes no longer active from the list - all without disturb- 
ing the user's selections in the list. It first calls NBPLookUp to 
get the names of all Chatterboxes, then it extracts one name at a 
time using NBPExtract. Each name is compared to those in the 
list; if there's a match, that entry is marked as “found” and the 
next name is processed. If the name is not found in the list, it's 
added. After all of the names have been extracted, any names not 
marked as “found” are deleted from the list. This would all be 
better handled by a custom LDEF, but I'll save that for another 
day. 

Toreceive messages with DDP, a program must first ask for 
them and provide a buffer to store them in. The AskForMessages 
routine takes care of this. It's very simple, just a single call to 
DDPRead. In this case, DDPRead is called with the async 
parameter set to true, meaning that the program will go on with 
its business while it waits for a message to come in. Once 
DDPRead has been called, it's the program's responsibility to 
watch the abResult field of the InABRecord parameter block to 
go to zero or a negative value. DDPRead sets this field to a 
positive number - the socket listener will set it to zero (if 
everything is OK) or negative (the error code) when a message 
comes in. In Chatterbox, the abResult field is examined once 
each time a null event is received. 

When a message has been detected, the ReadMessage rou- 
tine is called to pull the message out of the buffer and display it 
in the incoming messages field. As soon as the message is dealt 
with, ReadMessage calls AskForMessage to get ready for the 
next message. | 

Sending messages is simple too. When the user hits «re- 
turn» to send a message, it's pulled out of the TextEdit field and 
put into a message buffer. The program then runs through the 
user list, building a parameter block for each user selected and 
calling DDPWrite to send the message. Sometimes the Send- 
Message routine must be called upon to send a message to 
everyone in the list, even if they aren't selected (this happens 
during the start-up greeting, for example). In this case, the calling 
routine sets the toAll parameter true. 

When the user quits the program, it again sends out a special 
message that starts with a non-breaking space. This time it's an 
"adios" message. This message, like the greeting message, is 
used to tell all of the other Chatterbox programs in the zone to re- 
build their lists of users, since one has just quit. 


Extras and Options 
That's the bulk of the program, but there are a few extras. 
There are two buttons in the window for frequently-used tasks. 
The Scan button just looks for Chatterboxes on the network. The 
user can press it if things seem a little screwy or out of sync - it's 
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really just a security blanket, it's rarely needed. The Select All 
button selects all of the users in the list, something I found most 
users do often. There are also three optional behaviors that can 
be set or unset in the Options menu. The first sets a flag that tells 
the program to beep with each incoming message. This is in case 
a message comes in when the user isn’t watching or the window 
is in the background under MultiFinder. The second option 
allows the user to see the messages transmitted echoed in the 
incoming message field. The last option allows the user to have 
all new users that come along be automatically selected as 
recipients. 


What next? 

So how could this program be improved? Well, it would be 
nice if the program let you pick the zone you wanted to chat in, 
instead of just letting you chat in your own. The AppleTalk Zone 
Information Protocol could be used to get a list of zones on the 
internet. It would also be nice if the incoming messages that were 
deleted from the TextEdit field as they scrolled off the top could 
instead be scrolled back down with a scroll bar. A file transfer 
facility would be nice. No doubt all of you out there can come up 
with more improvements. 

As you see, AppleTalk is easy to use. This simple, low-level 
approach, using DDP and NBP, could be used to implement 
games, e-mail, network copy protection schemes and so on. As 
more and more Macs are networked out there, network aware- 
ness becomes more and more a must for any application. 


Listing: Chatter.c 


Sinclude <AppleTalk.h» 


/*** defines */ 
Sdefine NULL OL 


"define MAXUSERS 64 
"define BUFSIZE 600 
Sdefine NONE 
Sdefine REGISTER 1 
Sdefine WAITING 2 
"define SCANNING 3 
Sdefine SENDING 4 
Sdefine RECEIVING 5 
Sdefine МАХТЕХТ 32000L 
"define  MAXMSG 50 
Sdefine DISPLINES 8 
"define  RETURNKEY ‘\@15’ 
"define —ENTERKEY “003” 


/*** data about a single user */ 
typedef struct UserRecord ( 
AddrBlock  addr; 
int found; 
) UserRecord; 


/*** Globals */ 

int DoneF 18g; 
WindowPtr TheWindow; 
ControlHandleScanButton; 
ControlHandleSelectAllButton; 


ListHendle UserList; 
TEHendle — MyMessage; 
TEHendle — InMessages; 
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MenuHandle AppleMenu; 
MenuHaendle — FileMenu; 
MenuHandle X EditMenu; 
MenuHendle OptionMenu; 
DDPProto — **InABRecord; 
UserRecord — OtherUsers MAXUSERS 1; 
EntityName MyEntityName; 
Ptr MyNameBuf ; 
Str255 MyName ; 
int MySocketID; 
int NumOtherUsers; 
int TheError ; 
int EchoF lag; 
int BeepF lag; 
int SelectF lag; 
char RecBuf f er [BUFSIZE]; 
Rect StatusR; 
Rect DragRect; 
[*22222zzzzzzz2zzzzzzzzX/ 
ie у 
EventRecord event; 
WindowPtr whichWindow; 
char key; 


Initialize 0); 


while C !DoneFlag ) ( 


GetNextEvent ( everyEvent, &event ); 
switch C event.what 2 ( 
case activateEvt: 
whichWindow = (WindowPtr event .message; 
if ( whichWindow == TheWindow ) ( 
if С event.modifiers & activeFlag ) ( 
TEActivate ( MyMessage ); 
LActivate ( true, UserList ); 
ShowControl € ScanButton ); 
iE SelectAliButton); 


else ( 
TEDeactivate ( MyMessage ); 
LActivate ( false, UserList ); 
HideControl С ScanButton ); 
es C SelectAllButton 2; 


break; 
case updateEvt: 
whichWindow = (WindowPtr event message; 
if С whichWindow == TheWindow ) ( 
BeginUpdate С TheWindow 2; 
DoUpdate С ); 
EndUpdate ( TheWindow ); 


break; 
case mouseDown: 
switch ( FindWindow ( event.where, 
&whichWindow ) ) { 
case inMenuBar : 
DoMenu (MenuSelectCevent.where)); 
break; 
case inSysWindow: 
SystemClick C&event, whichWindow); 
break; 
case inDrag: 
1f С whichWindow == TheWindow ) 
DragWindow ( TheWindow, 
event.where, &DragRect ); 
break; 
case inContent: 
1f С whichWindow == TheWindow ) ( 
1f (TheWindow != FrontWindow( )) 
SelectWindow ( TheWindow ); 
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else DoMouseDown ( event.where, InsertMenu С EditMenu, 0 ); 


event.modifiers ); OptionMenu = GetMenu ( 1003 ); 
) InsertMenu ( OptionMenu, 0 ); 
break; DrawMenuBar (); 
break; /*** make sure appletalk is available */ 
case autokey: 1f € CTheError = MPPOpen (2) != noErr ) 
case keyDown: ErrorAlert (*\PCan’t start AppleTalk, еггог:”, TheError); 
key = (char) Cevent.message $ charCodeMask); 
1f ( event.modifiers & cmdKey ) /*** get user's name */ 
DoMenu С MenuKey С key ) 2; h = (Handle) GetString С – 16096 ); 
else if ( key == RETURNKEY (| key == ENTERKEY ) if C h != NULL ) 
SendMessage ( false ); BlockMove € *h, MyName, (Clong) **h) + 1L ); 
else ( else MyNane(2] = 0; 
ForeColor ( greenColor ); ReleaseResource С h ); 
TEKey ( key, MyMessage ); NameDlog С ); 
1f ((*MyMessage)-? teLength > MAXMSGX 
TESetSelect С (long) MAXMSG, /*** open our window & init */ 
MAXTEXT, MyMessage 2; InitTheWindow С ); 
TEDelete ( MyMessage ); ) 
ForeColor С blackColor 2; /*===== process menu picks */ 
DoMenu € mResult ) 
break; long mResult; 
case nuliEvent: 
if С MySocketID == Ø ) StartAT € ); int theMenu, theItem, i; 
else ( Str255  dename; 
ShowStatus С WAITING ); DialogPtr  aboutdlog; 
if С C*InABRecord)->abResult <= 0 ) GrafPtr ^ curport; 
ReadMessage ( ); TEHandle te; 


TEIdle ( MyMessage ); 
theItem = LoWord С mResult ); 


break; theMenu = HiWord ( mResult ); 
switch С theMenu ) ( 
) case 1000: 
if С theIten == 1) { 
7 С); aboutdlog = GetNewDialog ( 2000, NULL, -1L ); 
i = 0; 
while ( !i ) ModalDialog ( NULL, &i ); 
/*===== initialize the Mac and my globals */ DisposDialog С aboutdlog ); 
Initialize () ) 
( else ( 
EventRecord event; GetItem С AppleMenu, theltem, daname ); 
Handle h; GetPort ( &curport ); 
OpenDeskAcc ( daname ); 
/*** init the mac rom stuff */ SetPort (С curport 2; 
InitGraf С &thePort 2; 
InitFonts (); break; 
InitWindows СО; case 1001: 
InitMenus О); if С theItem == 1 ) DoneFlag = true; 
TEInit C2; break; 
InitDialogs C OL ); case 1002: 
InitCursor (); ForeColor С greenColor ); 
FlushEvents ( everyEvent, 0 ); ewitch C theIten ) ( 
case 3: 
/*** set up 8 few globals ... */ TECut С MyMessage ); 
EchoFlag = BeepFlag = SelectFlag = true; break; 
DoneFlag = false; case 4: 
MyNameBuf = 9L; TECopy ( MyMessage ); 
InABRecord = (DDPProto **) break; 
NewHandle ( sizeof ( DDPProto ) ); case 5: 
MoveHHi ( InABRecord ); TEPaste ( MyMessage ); 
HLock ( InABRecord ); 1f (C*MyMessage)-> teLength > MAXMSG X 
DragRect = screenBits.bounds; TESetSelect ( (long) MAXMSG, 
MySocketID = 0; | MAXTEXT, MyMessage 2; 
NumOtherUsers = 0; TEDelete ( MuMessage ); 
/*** read in the menus */ break; 
AppleMenu = GetMenu ( 1000 ); 
InsertMenu С AppleMenu, 0 ); ForeColor ( blackColor ); 
AddResMenu ( AppleMenu, ‘DRVR’ ); break; 
FileMenu = GetMenu ( 1001 ); case 1003: 
InsertMenu С FileMenu, 0 ); switch С theIten ) ( 
EditMenu = GetMenu ( 1002 ); case !: 
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1f ( BeepFlag ) ( 
BeepFlag = false; 
CheckI tem (OptionMenu, 1, false ); 


else ( 
BeepFlag = true; 
oo COptionMenu, 1, true ); 


break; 
case 2: 
if С EchoFlag ) { 
EchoFlag = false; 
ыы (OptionMenu, 2, false ); 


else ( 
EchoF lag = true; 
oe COptionMenu, 2, true ); 


break; 
case 3: 
if C SelectFlag ) ( 
SelectFlag = false; 
CheckI tem COptionMenu, 3, false ); 
else ( 
SelectFlag = true; 
ын (OptionMenu, 3, true ); 
break; 


break; 


HiliteMenu(0); 
) 


===== get the name the user wants to go bu */ 
I C 2 


DialogPtr dlog; 


int itype, item; 
Handle h, namefield; 
Rect r; 


647255 astr; 


/*** do the dialog */ 

dlog = GetNewDialog C 1000, ØL, -1L ); 
GetDItem ( dlog, 4, &itype, &namefield, &r ); 
SetIText € namefield, MuName ); 

SellText ( dlog, 4, 0, 255 ); 

item = 0; 

while ( item != 1 ) ModalDialog ( OL, &item ); 


/*** save off the name, 32 chars max */ 
GetIText ( namefield, &MyName ); 

if С (Cint) *MyName) > 31 ) *MyName -(сһаг) 31; 
CloseDialog ( dlog ); 

===== initialize AppleTalk stuff */ 

artAT ( ) 


/*** open a socket, use defalut listener */ 
if ¢ 


СТћеЕггог = DDPOpenSocket C&MySocketID,NULL)) != noErr ) 
ErrorAlert С *\PDDPOpenSocket С ) returned:*, TheError ); 


RegisterName ( ); 
CheckForUsers € ); 
SendGreeting С 2; 


/*** listen for messages */ 
AskForMessage С 2); 
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) 


/*=== Register MyName as a "Chatterbox^ via AppleTalk NBP */ 


RegisterName (С ) 


int len; 
NBPProto X **myABRecNBP; 


/*** show some feedback */ 
ShowStatus ( REGISTER ); 


/*** make up a handle for registering */ 
myABRecNBP = (NBPProto **) 

NewHandle ( sizeof ( NBPProto ) 5; 
HLock С myABRecNBP 2; 


/*** set up our entity name */ 

BlockMove С MyName, MyEntityName.objStr, 
(Clong) *MyName) + IL ); 

BlockMove С “\PChatterbox’, 

MyEntityName.typeStr, 11); 

BlockMove С “\P*”, MyEntityName.zoneStr, 2L ); 


/*** set up a buffer for NBP’s internal use */ 
len = (Cint) *MyName) + 26; 
MyNameBuf = NewPtr ( (long) len ); 


/*** fill in the record & register */ 
(*myABRecNBP )-> abOpcode = tNBPRegister; 
(*myABRecNBP )-» abUserReference = ØL; 
C*myABRecNBP )->nbpEntityPtr = &MyEntityName; 
(*myABRecNBP )->nbpBufPtr = MyNameBuf ; 
(*myABRecNBP )->nbpBuf Size = len; 
(*myABRecNBP )->nbpAddress.aSocket = (Byte) 
MySocketID; 
(*myABRecNBP )->nbpRetransmitInfo. 
retransInterval = 8; 


C*nyABRecNBP )-» nbpRetransmitInfo.retransCount = 2; 
if С (TheError = NBPRegisterCmyABRecNBP, false)) != noErr ) 
ErrorAlert С “\PNBPRegister С ) returned:”, TheError ); 


HUnlock С myABRecNBP ); 
po oe ( myABRecNBP ); 


/*===== remove the name from NBP */ 
UnRegisterName ( ) 


if С (TheError = NBPRemoveC&MyEntituName )) != noErr ) 
ErrorAlert С “\PNBPRemove С ) returned:^, TheError ); 


rales C MyNameBuf ); 


/*===== check for other users on the net. */ 
yb SLE С) 


int j, r, i, numFound, found, removed; 
Point c; 

EntityName otherEntitu; 

NBPProto — **otherABRecNBP; 

AddrBlock addb lock; 


/*** show some feedback */ 
ShowStatus ( SCANNING ); 


/*** mark them all as “not found” */ 
for ( i = 0; i < NumOtherUsers; ++i ) 
OtherUsers[il.found = false; 


/*** now scan for other users */ 
BlockMove С “\P=”, otherEntity.objStr, 2L ); 


BlockMove С "MPChatterbox^, otherEntity.typeStr, 11L ); 


BlockMove С “\P*%, otherEntity.zoneStr, 2L ); 
otherABRecNBP = (NBPProto **) 


NewHandle ( sizeof ( NBPProto ) ); 
HLock ( otherABRecNBP ); 
(*otherABRecNBP)->abOpcode = tNBPLookup; 
C*otherABRecNBP )-? abUserReference = QL; 
C¥otherABRecNBP )->nbpEntityPtr = &otherEntity; 
C*otherABRecNBP )->nbpBufPtr = NewPtr С 4096 ); 
(*otherABRecNBP )->nbpBufSize = 4096; ) 
(*otherABRecNBP )->nbpDataField = 40; ) 
(*otherABRecNBP)- »nbpRetransnitinfo. 
retransInterval = 8; 
C*other ABRecNBP )->nbpRetransmitinfo. 
retransCount = 1; 
1f (CTheError = NBPLookupCotherABRecNBP, false?) != noErr) 
ErrorAlert С “\PNBPLookup € ) returned:^, TheError 2; 


BlockMove С &OtherUsers[j*1], 
&OtherUsers[ 7], 
(long) CC(NumOtherUsers- j) 
*sizeof(UserRecord)) 2; 
р" С 1, j, UserList ); 


DisposPtr € C*otherABRecNBP)->nbpBufPtr ); 
HUnlock С otherABRecNBP ); 
yo une ( otherABRecNBP ); 


/*===== tell DDP we're waiting for a msg */ 


/*** 1 we found any, check for them in the AskForMessage ( ) 


list, else empty the list */ 
numFound = (*otherABRecNBP)-»nbpDataF ield; 
1f С numFound <= Ø ) { 
j = (UserList)-»dataBounds.bottom; 
if C j> 0 > LDelRow € j, Ø, UserList ); 
NumOtherUsers = 0; 


else ( 
for Cis 0; i < numFound; ++i ) { 


/*** extract it */ 

if С (TheError = NBPExtract ( 
C*otherABRecNBP )->nbpBufPtr, 
numFound, i*1, &otherEntity, 
&addblock )) == noErr ) ( 


/*** see if it's in the list */ 
found = false; 
for ( j = 8; j < NumOtherUsers; **j ) ( 
if С OtherUsers(jl.addr.aSocket == 
addblock.aSocket && 
OtherUsers[j].addr.aNode == 
addblock.aNode && 
OtherUsers[j].addr.aNet == 
addblock.aNet ) { 
found = true; 
eas 


) 


/*** if it is, mark it */ 
1f ( found ) OtherUsers[j].found=true; 


/***else add it, select it if auto-select is on */ 
else ( 
E : = 0; 
= NunOtherUsers; 
otharüsers [iced ther surs, addr = 
addb lock; 
OtherUsers [Num0therUsers).found = 
true; 
LAddRow С 1,NumOtherUsers,UserL ist ); 
LSetCell (С &otherEntity.objStr [1], 
Cint) otherEntity.objStr(0], c, UserList ); 
1f С SelectFlag ) 
LSetSelect € true, c, UserList ); 
++NumOtherUsers ; 


/*** don’t overflow */ 
) f С NumOtherUsers >= MAXUSERS ) break; 


) 


/**delete any that were not found (theu ve logged off) */ 


for С j = NumOtherUsers-1; j >= 0; -j ) { 
if С !OtherUsers[j). found )( 
-NumOtherUsers; 
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(*InABRecord)->abOpcode = tDDPRead; 
(*InABRecord)->abResult = 0; 
(*InABRecord)- » abUserReference = OL; 
(*InABRecord)-»ddpType = 5; 
(*InABRecord)->ddpSocket = MySocketID; 
(*InABRecord)->ddpReqCount = BUFSIZE; 
(*InABRecord)-?ddpDataPtr = RecBuf fer; 
if С (TheError = DDPRead ( InABRecord, true, 
true)) != noErr ) 
ErrorAlert С “\PDDPRead C ) returned:^, TheError ); 


===== read a message from the socket */ 


E ds ( 2 


Rect r; 

Cell с; 

Str255 othername; 

int i, namelen, nlines, fromnode; 


/*** make sure there's really a message */ 
if С C*InABRecord)->ddpActCount > Ø ) { 


/*** show some feedback */ 
ShowStatus С RECEIVING 2; 


/*** check for users if it’s a special 
message Cie, has option-space) */ 
if С RecBuffer[0] == ' ’ ) CheckForUsers СО; 


/*** see who it’s from */ 
namelen = 0; 
fromnode = (*InABRecord)-? ddpAddress . aNode; 
for ( i = 0; i < NumOtherUsers; ++i ) 
if С fromnode == 
OtherUsersli].addr.aNode ) break; 
1f С i < NumOtherUsers ) ( 
c.h = 0; 
С.У = i: 
namelen = 32; 
LGetCell € othername, &namelen, c, UserList ); 


/*** put the message in the display */ 

ForeColor ( blueColor ); 

TESetSelect € MAXTEXT, MAXTEXT, InMessages ); 

TEInsert € RecBuffer, (long) C*InABRecord2-? ddpActCount, 

InMessages ); 

TEInsert € ^ С“, 2L, InMessages 2; 

TEInsert € othername, (long) namelen, InMessages ); 

TEInsert ( “71015”, 2L, InMessages ); 

nlines = (*InMessages)-nL ines; 

for ( i = DISPLINES; i < nlines; зі ) 
DeleteFirstLine ( InMessages ); 

ForeColor (С blackColor 2; 


1f ( BeepFlag ) SysBeep ( 1 ); 
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DisposHandle ( outABRecord ); 
else ErrorAlert С “\PError in recieved packet.”, 0 ); ) 


AskForMessage ( ); /*===== say hello to existing users */ 
) E ( ) 
/*===== send the message out. If (АТТ is true, Str255 greeting; 
send to all, else send to selected. */ 
SendMessage С {0А11 ) /*** send log-on messge Chas option-space) */ 
int toA11; greeting(0] = 40” 
( Pstrcat ( greeting, "MP Hello Everyone!” ); 
DOPProto X **outABRecord; TESetSelect С ØL, ØL, MyMessage ); 
Handle thetext; TEInsert € &greeting[1], (long) greeting[0], MyMessage ); 
int i, nlines, textlen, msgSent; SendMessage ( true ); 
Cell c; TESetSelect € ØL, MAXTEXT, MyMessage ); 
char xmi tBuf fer [BUFSIZE); |. ( MuMessage ); 
/*** only if there is something to sau */ 
if С (*MuMessage)-)teLength <= Ø )return; /*===== pick up our tous and go home */ 
BueBue ( ) 
/*** get a record */ 
outABRecord = (DDPProto **) Str255 adios; 
NewHandle ( sizeof ( DDPProto ) ); 
HLock С outABRecord ); /*** send logoff message Chas option-space) */ 
adios[0] = 4%” 
/*** copy the text to the out buffer, empty Pstrcat ( adios, “V ^ ); 
TextEdit record */ Pstrcat ( adios, MyName ); 
thetext = (Handle) TEGetText С MyMessage 2; Pstrcat ( adios, "ҮР is off!” ); 
HLock € thetext ); TESetSelect € 0L, OL, MyMessage ); 
textlen = (*MyMessage)-? teLength; TEInsert € &adios(11, (long) adios[01, MyMessage ); 
BlockMove С *thetext, xmitBuffer, textlen ); SendMessage ( true ); 


HUnlock € thetext 2; 
/*** close everything */ 


/*** send the message to appropriate users */ UnRegisterName ( ); 
for(msgSent-false,i-0; i<NumOtherUsers; ++i) { DDPCloseSocket ( (Byte) MySocketID ); 
c.h = 0; CloseWindow ( TheWindow ); 
c.v = i; ) 
if C ОАТ! || 
LGetSelect ( false, kc, UserList ) ) { /*===== delete the first line from the given TEhandle */ 
ShowStatus ( SENDING ); DeleteFirstLine ( te ) 
(C*outABRecord2-?abOpcode = tDDPWrite; TEHandle te; 
C*outABRecord)-> abUserReference = ØL; ( 
(*outABRecord)->ddpType = 5; Handle h; 
(*outABRecord)-?ddpSocket = MySocketID; int charsinline = 0; 
(*outABRecord)-?ddpAddress = char *cp; 
OtherUsers([i].addr; 
C*outABRecord)->ddpDataPtr = xmitBuffer; h = TEGetText С te ); 
C*outABRecord2-? ddpReqCount = textlen; HLock € h 5; 
if ( (TheError = DDPWrite С outABRecord, cp = *h; 
false, false )) != noErr ) while С *cp != “N0152”)(0( 
ErrorAlert С “\PDDPWrite € ) returned:^, TheError ); ++cp; 
msgSent = true; ++charsinline; 
) ++charsinline; 
TESetSelect С ØL, (long) charsinline, te ); 
1f ( msgSent ) ( TEDelete ( te ); 
TESetSelect ( ØL, MAXTEXT, MuMessage ); ) 
TEDelete ( MuMessage ); 
TESetSelect ( @L, @L, MuMessage ); /*===== open and initialize the window */ 
InitTheWindow ( ) 
if С EchoFlag ) ( ( 
ForeColor ( blueColor ); Rect r, dbr, view, dest; 
TESetSelect СМАХТЕХТ, МАХТЕХТ, InMessages); Point csize; 
TEInsert С "«^, 1L, InMessages ); char title[80]; 
TEInsert € xmitBuffer, (long) textlen, InMessages ); 
TEInsert С *»M215^, 2L, InMessages ); TheWindow = GetNewWindow С 1000, ØL, -1L ); 
nlines = (*InMessages)->nLines; title[0] = 40” 
for ( i = DISPLINES; i < nlines; ++1 ) Pstrcat € title, “\PChatterbox - * ); 
DeleteFirstLine ( InMessages ); Pstrcat ( title, MuName ); 
ForeColor ( blackColor ); SetWTitle ( TheWindow, title ); 
) SetPort ( TheWindow ); 
) TextFont ( 4 ); 
TextSize ( 9 ); 
HUnlock ( outABRecord ); TextFace С Ø ); 
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MoveTo С StatusR.left, StatusR.top-4 ); 


/*** add in the controls */ DrawString С “\PStatus:” 2; 
ScenButton = GetNewContro! C 1000, TheWindow ); FrameRect С &StatusR 2); 
SelectAllButton = ShowStatus С NONE ); 
GetNewControl ( 2000, TheWindow ); ) 
/*** add in the user list */ /*===== display the status notice */ 
SetRect С іг, 20, 22, 164, 94 ); ShowStatus ( status ) 
SetRect ( &dbr, 0, Ø, 1, Ø ); int status; 
csize.v = 12; ( 
csize.h = 300; Rect r; 
UserList = LNew ( &r, &dbr, csize, 0, char жср; 
TheWindow, true, false, false, true ); static int oldstatus; 
/*** add in the outgoing message field */ if ( status != oldstatus ) ( 
SetRect ( &view, 21, 114, 339, 128 ); InsetRect ( &StatusR, 2, 2 ); 
SetRect ( &dest, 22, 115, 338, 270 ); EraseRect ( &StatusR ); 
MyMessage = TENew (С &dest, &view 2; ForeColor ( redColor ); 
TESetSelect С ØL, ØL, MyMessage ); cp = NULL; 
switch C status ) ( 
/*** set up the incomming message area */ case NONE: 
SetRect ( &view, 21, 148, 339, 238 ); break; 
SetRect ( &dest, 22, 149, 338, 270 ); case REGISTER: 
InMessages = TENew ( &dest, &view ); cp = “\PRegistering on the network. ^; 
TESetSelect ( OL, OL, InMessages ); break; 
case WAITING: 
/*** set up the status area */ cp = “\PListening..’; 
SetRect ( &StatusR, 196, 21, 340, 65 ); break; 
) case SCANNING: 
cp = "MPScanning for other users."; 
/*===== handle update events for our main Cand only) window */ break; 
DoUpdate С ) case SENDING: 
( ср = “NPSending теѕѕаде. *; 
Rect г; break; 
RgnHandle vis; case RECEIVING: 
cp = “\PReceiving message. ”; 
/*** do the controls */ break; 
SetPort ( TheWindow ); 
DrawControls С TheWindow ); 1f ( cp != NULL ) 
| TextBox € (cp + 1), Clong) *cp, &StatusR, teJustLeft ); 
/*** show the user list */ ForeColor ( blackColor ); 
r = (*UserList)->rView; InsetRect ( &StatusR, -2, -2 ); 
InsetRect € &r, -1, -1 ); oldstatus = status; 
FrameRect С &r ); 
MoveTo € r.left, r.top-4 ); ) 
DrawString С “\PSelect Recipients:^ ); 
vis = TheWindow- visRgn; /*===== handle mouse-downs in our window */ 
HandToHand ( &vis ); DoMouseDown ( thePt, mods ) 
LUpdate ( vis, UserList ); Point thePt; 
DisposHandle ( vis ); he mods; 
/*** show the MyMessage field */ Rect г; 
г = (*MuMessage)-,viewRect; Point localPt, с; 
Movelo ( r.left-1, r.top-6 ); ControlHandle chan; 
DrawString С “\PType a message, «return? to send:^ ); 
EraseRect ( &r ); /*** get the local point */ 
InsetRect ( &r, -2, -2 ); localPt = thePt; 
FrameRect С &r ); GlobalToLocal ( &localPt ); 
ForeColor С greenColor ); 
TEUpdate ( &r, MyMessage ); /*** in UserList or it’s scroll bars? */ 
ForeColor ( blackColor ); r = (*UserList)->rView; 
r.right += 16; 
/*** show the incomming message field */ 1f С PtInRect С localPt, &r ) && 
г = (*InMessages)- viewRect; ( NumOtherUsers > 0 ) ) { 
MoveTo С r.left-1, r.top-6 2; LClick € localPt, mods, UserList ); 
DrawString С “\PReceived Messages: " 2; return; 


EraseRect С &r 2; 
InsetRect ( &r, -2, -2 5; 


FremeRect ( &r ); /*** in MyMessage ? */ 
ForeColor С blueColor 2); г = (*MyMessage)->viewRect; 
TEUpdate ( &r, InMessages ); if С PtInRect € localPt, &r ) ) ( 
ForeColor ( blackColor ); TEClick ( localPt, 

((mods & shiftKey) == shiftKey), 
/*** show the status area */ MyMessage ); 
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return; 


/*** in the controls */ 
if (FindControlClocalPt, TheWindow, &chan)) ( 
if С TrackControl С chan, localPt, NULL ) )( 
1f ( chan == ScanButton ) CheckForUsers(); 
if С chan == SelectAllButton 2 ( 
for ( c.h = 0, c.v = (*UserList)->dataBounds.top; 
c.v < C*UserList)-^dataBounds.bottom; **c.v ) 
LSetSelect С true, c, UserList ); 


/*===== catenate the second pascal string to the first */ 
Pstrcat С stri, str2 ) 
char *stri, *str2; 


char *strilen, *str lend; 


strilen = str1; 

striend = str! + (int) *strilen + 1; 

BlockMove ((str2 + 1), striend, (long) *str2); 
*strilen += (int) *str2; 


/*=== alert the user to an error, optionally exit to shell */ 


ErrorAlert ( where, errorNum ) 
char *where; 
int errorNum; 


Str255 idstr; 


/*** give the alert */ 
NumToString € (long) errorNum, idstr 2; 
ParamText С where, idstr, ТАРУ, *VP” ); 
if C Alert С 666, ØL 2 == 1) { 
UnRegisterName С 2; 
DOPCloseSocket € (Byte) MySocketID ); 
г (5; 


) 
Listing: Chatter.r 


resource 'BNDL^ (128) ( 
‘chat’, 
g, 
( /* array TypeArray: 2 elements */ 
/* (1) */ 
215722 
( /* array IDArray: 2 elements */ 
/* (1) */ 
0, 128, 
/* [2] */ 
1, 129 


}, 
/* [2] */ 
‘FREF’, 
( /* array IDArray: 2 elements */ 
/* [1] */ 
0, 128, 
/* [2] */ 
1, 129 
) 
o) 
); 
data 'chat^ (0) ( 
ф* 15 43 68 61 74 74 65 72 62 6F 78 20 31 2E 30 20" 
$"62 79 20 52 6F 62 0D"); 
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resource “ІСМ8” (128) ( 

( /* array: 2 elements */ 

/* [1] */ 

$^1F FF FF F8 21 FF FF FC 41 FF FF FE 81 FF FF FF” 
Ф81 FF FF FF 81 FF CØ FF 89 ҒҒ 00 ЗЕ 99 FE 00 1F" 
$^89 FC 00 ØF 81 F8 00 07 81 F8 00 07 81 FO 00 03" 
$^80 F1 9D СЗ 80 FØ 00 03 80 70 00 03 80 71 00 43" 
%%80 70 00 03 80 70 00 03 80 F1 D7 03 87 FO 00 03" 
%%81 FØ 00 03 81 F1 EE СЗ 81 FO 00 07 81 FO 00 07" 
$781 FØ 00 OF 87 EO 00 IF 8F 80 00 ТЕ 87 FF FF ҒҒ” 
$"81 FF FF FF 41 FF FF FE 21 FF FF FC IF FF FF F8", 
/* [2] */ 
$"1F FF FF F8 ЗЕ FF FF FC TF FF FF FE FF FF FF ҒҒ” 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF” 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ҒҒ” 
$"FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF” 
$2FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF” 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF” 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF” 
ii FF FF FF ТЕ FF FF FE ЗЕ FF FF FC IF FF FF F8" 
); 


resource ‘WIND’ (1000, "Chatterbox”) ( 
(46, 16, 300, 376), 
documentProc, 
visible, 
noGoAway, 
0x0, 
“Chatterbox” 


resource ‘MENU’ (1000, “Apple”) ( 
1000, 
textMenuProc, 
Ox7FFFFFFD, 
enabled, 
apple, 
( /* array: 2 elements */ 
/* (1) */ 
“About Chatterbox.^, nolcon, noKey, noMark, plain, 
/* [2] */ 
E поІсоп, noKey, noMark, plain 


); 


resource ‘MENU’ (1001, “File”) ( 
1001, 
textMenuProc, 
allEnabled, 
enabled, 
"File", 
( /* array: 1 elements */ 
/* (1) */ 
“Quit”, noIcon, "Q^, noMark, plain 


); 


resource “MENU” (1002, “Edit”) ( 

1002, 

textMenuProc, 

QxTFFFFFFC, 

enabled, 

“Edit”, 

( /* array: 5 elements */ 
/* (1) */ 
“Undo”, nolcon, "Z", noMark, plain, 
/* [2] */ 
*-*, nolcon, noKey, noMark, plain, 
/* [3] */ 
“Cut”, nolcon, "X^, noMark, plain, 
/* 14] */ 
“Copy”, nolcon, “С”, noMark, plain, 
/* [5] */ 
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“Paste”, nolcon, *V^, noMark, plain 1, 0, 0, 0, 


/* [31 */ 
); | 2, 8856, 65535, 6900, 
/* (4) */ 
resource ‘MENU’ (1003, *Options^) ( 3, 7652, 8260, 65535, 
1003, /* [5] */ 
textMenuProc, 4, 65535, 9758, 8505 
allEnabled, Y; 
enabled, $^00 01 11 11 11 11 11 11 11 11 11 11 11 11 10 00" 
“Options”, $00 10 00 01 33 33 33 33 33 33 33 33 33 33 31 00" 
( /* erray: 3 elements */ %%01 00 00 01 33 33 33 33 33 33 33 33 33 33 33 10" 
/* (1) */ $^10 00 00 01 33 33 33 33 33 33 33 33 33 33 33 31" 
“Веер On Receipt”, noIcon, noKey, check, plain, $^10 00 00 01 33 33 33 33 33 33 33 33 33 33 33 31" 
/* (2) */ 9710 00 00 01 33 33 33 33 33 00 00 00 33 33 33 31" 
"Echo My Transmissions”,nolcon, noKey, check, plain, $10 00 10 01 33 33 33 33 00 00 00 00 00 33 33 31" 
/* [31 */ %%10 01 10 01 33 33 33 30 00 00 00 00 00 03 33 31" 
“Auto-select New Users^,noIcon,noKey, check, plain $^10 00 10 01 33 33 33 00 00 00 00 00 00 00 33 31" 
) $^10 00 00 01 33 33 30 00 00 00 00 00 00 00 03 31" 
); $^10 00 00 01 33 33 30 00 00 00 00 00 00 00 03 31" 
$^10 00 00 01 33 33 00 00 00 00 00 00 00 00 00 31" 
resource ‘ALRT’ (666, “Error Alert”) ( $^10 00 00 00 13 33 00 04 44 04 44 04 44 00 00 31" 
(162, 90, 330, 398), $^10 00 00 00 13 33 00 00 00 00 00 00 00 00 00 31" 
666, 6710 00 00 00 01 33 00 00 00 00 CO 00 00 CO 00 31" 
( /* array: 4 elements */ $10 00 00 00 01 33 00 04 44 40 44 04 04 00 00 31" 
/* (11 */ $10 00 00 00 01 33 00 00 00 00 00 00 00 00 00 31" 
OK, visible, soundi, $^10 00 00 00 01 33 00 00 00 00 00 00 00 00 00 31" 
/* (21 */ $^10 00 00 00 13 33 00 04 44 04 04 44 00 00 00 31” 
OK, visible, sound], $"10 00 01 11 33 33 00 00 00 00 00 00 00 00 00 31" 
/* (31 */ $^10 00 00 01 33 33 00 00 00 00 00 00 00 00 00 31" 
ОК, visible, sound], $^10 00 00 01 33 33 00 04 44 40 44 40 44 00 00 31" 
/* (4) */ $^10 00 00 01 33 33 00 00 00 00 00 00 00 00 03 31" 
ОК, visible, sound! $10 00 00 01 33 33 00 00 00 00 00 00 00 00 03 31" 
) $^10 00 00 01 33 33 00 00 00 00 00 00 00 00 33 31" 
); $^10 00 01 13 33 30 00 00 00 00 00 00 00 03 33 31" 
$^10 00 13 33 30 00 00 00 00 00 00 00 03 33 33 31" 
resource “сісп” (1000) ( $^10 00 01 13 33 33 33 33 33 33 33 33 33 33 33 31" 
16, . $?10 00 00 01 33 33 33 33 33 33 33 33 33 33 33 31" 
(0, 0, 32, 32), %%01 00 00 01 33 33 33 33 33 33 33 33 33 33 33 10" 
0, %%00 10 00 01 33 33 33 33 33 33 33 33 33 33 31 00" 
unpacked, $^09 01 11 11 11 11 11 11 11 11 11 11 11 11 10 00" 
0, ; 
0x480000, 
0x480000, resource ‘DITL’ (1000) ( 
chunky, ( /* array DITLarray: 4 elements */ 
4, /* [1] */ 
1, (80, 52, 100, 112), 
4, Button ( 
0, enabled, 
0, “Оқ” 
4, J; 
(0, 0, 32, 32), /* (2) */ 
4, (8, 8, 40, 40), 
(0, 0, 32, 32), Icon ( 
$”ІҒ FF FF F8 ЗЕ FF FF FC ТЕ FF FF FE FF FF FF ҒҒ” disabled, 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF” 1000 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ҒҒ” ), 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ҒҒ” /* [31 */ 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ҒҒ” (16, 52, 36, 288), 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ҒҒ” StaticText ( 
$^FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ҒҒ” enabled, 
$^FF FF FF FF ТЕ FF FF FE ЗЕ FF FF FC JF FF FF ЯҒ”, "Enter the name you want to go by:” 
$^1F FF FF F8 21 FF FF FC 41 FF FF FE 81 FF FF FF” А 
$^81 FF FF FF 81 FF CØ FF 89 FF 00 ЗЕ 99 FE 00 IF” /* [4] */ 
$89 FC 00 OF 81 F8 00 07 81 F8 00 07 81 FO 00 03" (48, 56, 64, 256), 
$^80 F1 00 СЗ 80 FO 00 03 80 70 00 03 80 71 DD 43" EditText ( 
$^80 70 00 03 80 70 00 03 80 F1 07 03 87 FO 00 03" enabled, 
$"81F0 00 03 81 F1 EE СЗ 81 FO 00 07 81 FO 00 07" e» 
$^81 FO 00 OF 87 EO 00 IF BF 80 00 ТЕ 87 FF FF ҒҒ” ) 
$^81 FF FF FF 41 FF FF FE 21 FF FF FC IF FF FF F8" ) 
,üx0, 0, ); 
( /* array ColorSpec: 5 elements */ 
/* [1] */ resource ‘DITL’ (666) ( 
0, 65535, 65535, 65535, ( /* array DITLarray: 6 elements */ 
/* (2) */ /* (1) */ 
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(128, 16, 152, 128), 
Button ( 

enabled, 

“Exit To Shell” 


), 
/* [2] */ 
(128, 168, 152, 296), 
Button ( 
enabled, 
“OK, Keep Going’ 


/* [3] */ 
(8, 8, 40, 40), 
Icon ( 
disabled, 
1000 
), 
/* [4] */ 
(16, 48, 40, 296), 
StaticText ( 
disabled, 


“Oops! Something bad has happened: * 


), 

/* [5] */ 

(48, 48, 80, 296), 

StaticText ( 
disabled, 
waga 

), 

/* [6] */ 

(88, 48, 112, 296), 

StaticText ( 
disabled, 
"w^ ]4 

) 

) 
); 


resource 'DITL^ (2000) ( 
( /* array DITLarray: 1 elements */ 
/* (1) */ 
(2, 8, 98, 313), 
Picture ( 
enabled, 
2000 


) 
); 


resource ‘ICON’ (1000, purgeable) ( 

$^lF FF FF F8 21 FF FF FC 41 FF FF FE 
$^81 FF FF FF 81 FF CO FF 89 FF 00 ЗЕ 
$^89 FC 00 OF 81 ЕВ 00 07 81 F8 00 07 
$"80 F1 00 СЗ 80 FO 00 03 80 70 00 03 
%%80 70 00 03 80 70 00 03 80 F1 07 03 
981 FO 00 03 81 F1 EE СЗ 81 FO 00 07 
$?81 FØ 00 OF 87 EO 00 IF ВЕ 80 00 ТЕ 
A FF FF FF 41 FF FF FE 21 FF FF FC 


resource ‘DLOG’ (1000, “Get Name”) ( 
(66, 40, 178, 360), 

altDBoxProc, 

visible, 

goAway, 

0x0, 

1000, 

“What’s your name?” 


); 


resource 'DLOG^ (2000, "About..." ( 
(40, 40, 140, 360), 
dBoxProc, 
visible, 
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81 
99 
81 
80 
87 
81 
87 
IF 


FF FF ҒҒ” 
FE 00 1F” 
FO 00 03" 
71 DD 43" 
FO 00 03" 
FO 00 97" 
FF FF FF^ 
FF FF F8" 


goAway, 

0x0, 

2000, 

“New Dialog" 
); 


resource ‘FREF’ (128) ( 
‘APPL’, 
0, 


); 


resource 'CNTL^ (1000, “Scan”) ( 
(75, 274, 95, 340), 
0, 
visible, 
1, 
0, 
pushButProc, 


ГА 
*Scan^ 


); 


resource 'CNTL^ (2000, "Select All”) ( 


(75, 196, 95, 264), 
0, 
visible, 
1, 
0, 
pushButProc, 
0, 
) “Select All’ 


resource ‘vers’ (2) { 
0x1, 
0x0, 
0х0, 
0х0, 
verUs, 
"1.0", 
“ ру Rob НаГегпік” 


2 


resource ‘vers’ (1) ( 
0x1, 
0x0, 
0x0, 
0x0, 
verUs, 
71.87, 
10” 
); 


resource ‘PICT’ (2000) ( 
(191, 81, 287, 386), 
VersionOne ( 

( /* array OpCodes: 4 elements */ 
/* [1] */ 
shortComment ( 

130 
13 
/* [2] */ 
clipRgn ( 
0, 0, 720, 516), 


^; 

/* (3] */ 

packBitsRect ( 
40, 
(191, 80, 287, 392), 
(191, 81, 287, 386), 
(191, 81, 287, 386), 
srcCopy, 
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$"02 09 00 02 DO 00 02 09 00 08 00 01 F1 FF 00 80" %%40 00 00 20 20 00 10 00 OF EO FC 00 03 01 FC 20" 


$^EB 00 09 01 02 IF F2 FF 00 CO EB 00 09 01 04 IF” $^08 FD 00 00 80 FE 00 25 06 06 OC 00 02 00 01 04" 
$^"F2 FF 00 Ей ЕВ 00 09 01 08 IF F2 FF 00 FO ЕВ 00" $^FE 00 0C 20 80 04 40 00 00 30 60 00 10 00 08 10" 
$"09 01 08 1F F2 FF 00 FO EB 00 ØB 02 08 IF FC F4" $“FC 00 03 01 02 00 08 FD 00 00 80 FE 00 28 24 05" 
%%00 01 OF FØ ЕВ 00 08 02 08 OF FØ F4 00 01 03 FO" 9714 F9 ТА 10 01 08 ЗЕ 5E 00 21 07 CF ТЕ 41 00 28" 
$"EB 00 08 02 09 ОҒ EO F4 00 01 01 FO ЕВ 00 BA 02" %”А7 CB 00 80 08 ØA 09 F2 F2 F1 FO 01 01 65 E8 40" 
%%08 9F CO ЕЗ 00 00 FO ЕВ 00 ØA 02 08 IF 80 ЕЗ 00" $“1F 2F ІҒ 80 РЕ 00 28 24 04 А5 05 82 20 01 10 41" 
%%00 70 ЕВ 00 QA 02 08 ІҒ 80 ҒЗ 00 00 70 ЕВ 00 26" $^61 00 22 08 24 41 41 00 25 28 2C 11 00 08 BA ØA” 
$^08 08 IF 00 ТЕ C6 00 00 OC OC FE 00 00 CO FD 00" $"08 ØB ØA 08 01 01 26 08 80 20 BØ AØ 80 FE 00 28" 
$"0E 30 IF F8 00 00 ІР F8 00 18 00 03 01 80 00 78" $^17 04 44 05 02 40 01 FO 41 41 00 ЗЕ 00 24 41 41" 
$^FD 00 00 Сб FE 00 26 08 08 OF 00 CO 66 00 00 OC" $"00 22 20 28 12 00 08 ØA 08 FE BA 09 08 01 01 24" 
$"0C FE 00 00 CO FD 00 OE 30 18 BC 00 00 18 BC 00" $^09 00 00 Ай AQ 80 FE 00 28 24 04 04 FD 03 CO 01" 
$^18 00 03 01 80 00 CO FD 00 00 06 FE 00 29 25 08" %%08 ТЕ 41 00 21 07 E4 41 41 00 20 27 E8 1E 00 08" 
$’OF 00 CO 07 F8 ТЕ 1Е OF ВЕ ЕЗ FE FF OF ЕЗ 06 00" $^0^ 09 FA ØA ØB F8 01 01 24 OF 00 IF AD AØ 80 FE" 
$^30 18 ØC C1 80 18 ØC 7F IF EO 03 01 ВЕ ЕЗ F8 FE” %%00 26 15 04 05 05 02 20 01 04 40 41 00 20 88 24" 
$“3F EF F1 Сб 18 ҒҒ 00 29 25 08 07 00 CØ 06 BC C1" $"41 41 00 20 28 28 11 00 08 FC QA 09 00 01 01 24" 
%”8С ØC 18 33 80 C1 98 31 8C 00 30 18 ØC C1 80 18" $^"08 80 20 А0 А0 80 FE 00 28 17 04 05 05 02 10 01" 
$"0C СІ 98 30 03 01 98 30 СІ 83 38 BE 18 C6 30 ҒҒ” $^02 41 41 00 20 48 24 41 41 00 20 28 28 10 80 08" 
$"00 29 25 08 07 00 CO 06 ØC 01 BC OC 18 33 00 СІ" $^12 1A FE ØA 09 08 01 02 24 08 40 20 А0 А0 80 FE” 
$"98 30 08 00 30 IF F8 C1 80 IF F8 C1 98 30 03 ҒҒ” $20 28 24 04 04 FD 02 09 01 01 ЗЕ 41 20 20 27 ЕЗ" 
$^80 30 C1 83 30 ØC 18 C6 60 FF 00 29 25 08 07 00" $"41 ЗЕ 20 20 27 E8 10 48 OF E1 E9 FA ØA 09 F1 01" 
$"C0 06 OC ТЕ 8C 0С IF ЕЗ 00 Ci 98 30 70 00 30 18" $^FC 24 08 20 ІҒ Ай OF 80 FE 00 17 FD 00 00 01 FD" 
$"0C C1 80 18 CO СІ 98 30 03 01 BF FØ СІ FF 30 0C" $"00 00 20 FD 00 01 01 20 FD 00 00 08 FB 00 00 01" 
$^18 СТ CO FF 00 29 25 08 07 00 CO 06 BC СІ 8C BC’ $“F5 00 17 FD 00 00 02 FD 00 00 40 FD 00 01 41 40" 
$^18 03 00 C1 98 30 70 00 30 18 ØC СІ 80 18 60 СІ" $^FD 00 00 10 FB 00 00 02 F5 00 06 ЕЗ 00 00 ЗЕ E8" 
$"98 30 03 01 98 30 СІ 80 30 OC 18 C6 60 FF 00 29" $20 02 09 00 02 DO 00 02 09 00 02 09 00 10 12 07" 
$225 08 OF 00 CO 06 ØC СІ 8C BC 18 03 00 C1 98 30" $^FD 00 00 07 F8 00 00 80 00 10 IF F8 00 00 CO 00" 
$"08 00 30 18 ØC C1 80 18 30 C1 98 30 03 01 98 30" $"00 1С FD 00 03 30 30 00 03 F4 00 10 12 00 41 00" 
%“С1 80 30 ØC 18 Сб 30 ҒҒ 00 29 25 08 ТЕ 00 CO 66" $"00 04 04 00 00 80 00 10 01 80 00 00 CO 00 00 OC" 
$°0С C1 8C ØC 18 33 00 C1 98 31 8C 00 30 18 OC СІ" $"FD 00 03 30 30 00 03 F4 00 20 ІС 00 41 F8 F8 04" 
$^80 18 18 C1 98 30 03 01 98 30 СІ 83 30 ØC 18 C6" $"04 F8 FO EO IF 3C 01 81 F8 FC FE ТЕ 1F 8C ТЕ 3F” 
$^18 FF 00 29 25 08 ІҒ 00 ТЕ Сб ØC ТЕ 87 87 8F ЕЗ" %“80 CO 30 33 ҒЗ FB 18 FC F6 00 20 1C 00 41 05 04" 
%%00 FF OF ЕЗ 06 00 30 IF F8 ТЕ 80 18 OC ТЕ IF EO" $"04 05 05 04 80 20 90 01 83 00 86 СЗ 71 BØ CC C3" 
$"03 01 8F FØ CØ FE 30 ØC 18 Сб ØC FF 00 ØD 01 08" $61 BØ CØ 30 36 1B 83 31 86 F6 00 20 1C 00 41 05" 
ӘУІҒ F2 00 04 30 00 00 01 80 EF 00 ØD 01 08 IF F2" $"04 07 F9 05 00 80 00 90 01 83 00 80 СЗ 61 BO CC" 
%%00 04 70 00 00 C1 80 EF 00 OC 01 08 IF F2 00 03" $^C3 61 BØ CØ 33 36 1B 03 61 80 F6 00 20 1C 00 41" 
$^70 00 00 ТЕ EE 00 00 01 08 IF F2 00 00 FO EB 00" $^05 FC 04 21 FC FC 80 ІҒ 90 01 83 FD 80 C3 61 BØ" 
$"0^ 01 08 ТЕ ҒЗ 00 01 01 FO EB 00 BA 01 08 FB ЕЗ" $^CC СЗ 61 BØ CØ 37 Вб 1B 03 EO FE F6 00 20 1C 00" 
$"00 01 07 FO EB 00 09 01 08 ТЕ F2 FF 00 FO EB 00" $”41 05 00 04 11 00 04 80 20 90 01 83 01 80 СЗ 61" 
$"09 01 08 IF F2 FF 00 FO EB 00 09 01 04 IF F2 FF" $°В0 CC СЗ 61 BØ CØ 3C F6 1B 03 30 06 F6 00 20 1C" 
$"00 EO EB 00 09 01 02 IF F2 FF 00 CO EB 00 08 00" $"00 41 05 04 04 09 05 04 80 20 90 01 83 0D 86 C3" 
%%01 F1 FF 00 80 ЕВ 00 02 09 00 02 09 00 02 DO 00" %%61 BØ CC СЗ 61 BØ CØ 38 76 1B 03 19 86 F6 00 20" 
$02 09 00 02 09 00 02 09 00 02 DO 00 02 09 00 02" 971С 00 41 04 F8 04 04 F8 F8 60 IF 8C 01 81 F8 FC" 
%%09 00 02 09 00 02 DO 00 02 DO 00 02 09 00 02 09" $^C3 61 9F 8C ТЕ ЗЕ ОҒ CØ 30 33 ЕЗ 03 ØC FC Еб 00" 
$"00 00 09 04 04 88 80 02 00 03 00 00 18 ЕЗ 00 00” $08 ED 00 02 01 80 CO FO 00 08 ED 00 02 61 BO CO" 
$"09 04 04 08 80 02 00 01 00 00 20 ЕЗ 00 10 OC 04" $°Ғ0 00 08 ED 00 02 ЗЕ IF 80 FO 00 02 09 00 02 09" 
$^05 9E FC 03 F1 F1 ЗЕ 00 ҒА ҒЗ ЕТ B9 Еб 00 10 QC" $^00 02 09 00" 

$04 04 88 82 02 ØA 09 20 80 23 04 14 44 Еб 00 10" ); 

$"0C 04 44 88 82 02 BA 09 20 80 22 04 14 44 EO 00" /* [4] */ 

9710 0С 04 A4 88 82 02 ØB FO 20 80 22 04 14 44 Еб" shortComment ( 

$"00 10 0С 05 14 88 82 02 BA 01 20 80 22 04 14 44" 131 

$^E6 00 10 ØC 06 ØC 88 82 02 BA 09 20 80 22 04 14" ) 

$^44 Еб 00 10 ØC 04 04 86 82 02 09 ҒІЗҒ 00 22 03" ) 

$"E4 45 E6 00 06 ҒА 00 00 20 E1 00 06 ҒА 00 00 20" ) - 
$"E1 00 02 09 00 02 09 00 02 09 00 02 09 00 02 DO" ); fang! 
$"00 25 06 04 04 00 02 00 01 02 FE 00 OC 20 40 04" ее 
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Jor Z 's Folder Jörg Langowski 
MacTutor Editorial Board 
C++ Sample Application MacTutor App Volume 5, Number 12 
“C++ Sample Application” public: 


As I am writing this, MPW C++ is shipping; version 3.1b1 
is available through APDA as of October 11. The following 
message could be found on Applelink: 


“On Tuesday, October 3, 1989 Apple Computer, 
Inc announced MPW C++ v.3.1B1 and said MPW C++ 
was available for ordering immediately and would be 
shipping later in October. ‘Later’ 15 here NOW! MPW 
C++ v.3.1B1 started shipping on Wednesday, October 
11, 1989! 

To get your copy, call APDA at 

1-800-282-2732 (U.S.) 

1-800-637-0029 (Canada) 

1-408-562-3910 (International) 

ask for part number M0346LL/A. The price is 
$175 and the package includes one Apple C++ Manual, 
three AT&T C++ manual (Product Reference, Library 
Manual, and Selected Readings), MacApp 2.0B9 pre- 
liminary C++ interfaces (so you can use MacApp from 
C++),and three 3.5" disks. 

Tim Swihart 

C++ Product Manager “ 


Thus, all people interested in C++ can now get their copies 
- and follow this tutorial. 

The example that I prepared for you this month is derived 
from one of the samples on the Apple C++ disks. Apple’s 
samples include a rudimentary application framework, some sort 
of a mini-MacApp, defined in the classes TApplication and 
TDocument. After last month’s introduction to some essential 
features of C++, ГІ show you this time how to use this frame- 
work to build a small application that opens and closes a window 
in which some text is displayed and handles one custom menu in 
addition to the Apple, File, and Edit menus. 

Since the base classes, TApplication and TDocument, 
provide for MultiFinder support, our application will also be 
fully MultiFinder compatible. I am not reprinting the full TAp- 
plication and TDocument framework here, “for copyright rea- 
sons” - the real reason being, of course, that it would make this 
article about ten pages longer, and those of you who use C++ have 
those files, anyway. However, we'll take a short look at the main 
features of those two classes. 

TApplication implements the basic behavior of a Macin- 
tosh application. This class provides, among other methods, the 
constructor for instantiating a new application object, and the 


public EventLoop routine: 
class TApplication : HandleObject ( 
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TApplicationCvoid); 
void EventLoop(void); 
.etc. .. 


) 


Note here that this class is derived from the superclass 
HandleObject; this is a special class particular to MPW C++, 
where space for the object is allocated through a handle, not a 
pointer, to prevent memory fragmentation. Another ‘special’ 
superclass is PascalObject, which is used to access class defini- 
tions in Object Pascal from C++, necessary for MacApp support. 
We'll discuss these classes in a later column. 

Most methods in TApplication are protected so that they 
can only be accessed by derived classes. They include basic event 
handlers and initializers which are called before and after the 
main event loop. Those methods are declared virtual which 
means they don’t have to be defined within the class TApplica- 
tion itself, and run-time binding will be supported where neces- 
sary. 
The behavior of our application will be completely deter- 
mined by the way we re-define TApplication’s methods. Of the 
base class, we only need the header file TApplication.h to make 
its definitions available to our particular implementation; the 
code for TApplication can be kept in a separate object file or a 
library. 

A simple program would define its own application class, 
say TMacTutorApp, and override some of the event handlers in 
TApplication. The main program then justconsist of calls to two 
methods, the constructor and the event loop: 


int main (void) 


gTheApplication = new TMacTutorApp; 
if CgTheApplication == nil) return 0; 
gTheApplication-»EventLoop? ); 

return 0; 


) 


A complete Macintosh application in five lines of C++ code! 
(I don’t count the braces). Of course, this simplicity is deceptive; 
all the work is done in the methods that determine the behavior 
of the event loop. Our application class, its associated document 
class, and the methods are implemented in listing 1; the header 
file that contains the definitions is shown in listing 2. 


Our Application 
Our application class re-defines TApplication’s construc- 
tor and six private methods. Listing 1 contains the actual code. 
Let’s explain the methods as they are called when the program is 
executed. 
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When the application object is constructed, first the con- 
structor of the base class, TApplication, is called. By default, 


this method initializes all the toolbox managers, determines 


whether there is enough memory and the system environment is 
OK torun the program, and does some other initializations. Then, 
TMacTutorApp’s constructor is called (listing 1); this method 
sets up the menu bar and creates one new document (DoNew(). 

Any application created using the TApplication framework 
contains a list of documents, whose maximum number is deter- 
mined by the constant k&MaxOpenDocuments in our application's 
class definition (Listing 2). The actual handling of this document 
list is implemented in TApplication itself and need not concern 
us here. As long as the number of open documents is less than 
kMaxOpenDocuments, the New, and possibly Open, items in the 
File menu are enabled; if the maximum number is reached, they 
will be disabled. This behavior is laid out in the AdjustMenus 
method. That method is called once on every pass through the 
event loop (also defined in the base class). 

Mouse downs (and other events) are automatically passed 
on to their respective handlers by TApplication. The routine that 
we need to override in our class definition to handle menu 
selections is DoMenuCommand (Listing 1). Here, the basic 
apple, File and Edit menu selection are treated in a more or less 
standard way; the fourth menu is our own addition and contains 
four items to choose from. When one is selected, that item will be 
checked while the others are unchecked (checking/ unchecking 
is done by AdjustMenus). Furthermore, the number of the se- 
lected item, as well as a corresponding string, are passed on to the 
open document. The document then knows which message to 
display in its window. 


Our Document 

The basic methods that are defined in the TDocument class 
deal with document display (i.e. window updating, growing/ 
zooming, activate/deactivate), editing (cut/paste, mouse down in 
content, key down), and file and print handling. All these meth- 
ods do nothing by default; they need to be overridden in our 
document’s class definition. 

Our document is called - what else - a TMacTutorDocu- 
ment, and the methods we redefine are the constructor, destruc- 
tor, window draw (private) and update methods. The constructor 
creates a new window and assigns an initial message to be 
displayed. When you look at its code (Listing 1), you'll notice 


that the first line looks somewhat funny: 
TMacTutorDocument : : TMacTutorDocument 


(short resID, StringPtr s) : CresID) (etc. ) 
This form of a function call is particular to C++ construc- 


tors. When a constructor is called, it will call the constructor of 
the base class first; this constructor might need another set of 
parameters. This parameter list is therefore given after the colon. 
In our case, we pass our window's resource ID to the base class 
constructor, which then creates a new window according to the 
resource information. Thereafter our own constructor code is 
called, which initializes the message string and makes the win- 
dow visible. 

The destructor will only hide our window; the actual delc- 
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tion of the object (DisposeWindow) is done in the base class, 
TDocument. 

DoUpdate will call our definition of DrawWindow, em- 
bedded in calls to BeginUpdate and EndUpdate. DrawWindow 
itself, which displays the message string in the window, is 
private; all window re-drawing is handled through calls to 
DoUpdate. 

Methods inside TMacTutorApp set and retrieve the se- 
lected menu item number in our document, and set the message 
string. We therefore need access to these variables, which are 
private to TMacTutorDocument. Such access is provided 
through the methods SetDisplayString, GetItemSelected, and 
SetItemSelected, which are defined inline in the header file 
(listing 3). 

Taking all these definitions together, you have an object- 
oriented framework for a very simple application. You see how 
easy it is to expand this framework to your own needs, and how 
well-separated the different parts of an application are in an 
object-oriented environment like C++. Application setup, menu 
handling (proper to the application), and window handling 
(proper to the document), are clearly distinct, as are the basic 
behavior (laid down in the application framework) and the user- 
defined behavior (by overriding the basic methods). 

I'll leave itat that for this month; next time we'll define our 
own family of objects that can be displayed and manipulated in 
a document window. If you have questions or comments regard- 
ing this column, interesting pieces of C-- code, or suggestions 
for improvement, feel free to contact me via MacTutoror through 
the network: LANGOWSKIQFREMBLSI.BITNET. 


Listing 1: MacTutorApp.cp - our application-specif ic 
class implementations 


/* 
8 MacTutorApp 
t 


A rudimentaru application skeleton 
based on an example given bu Apple MacDTS 
@ J. Langowski / MacTutor 1989 


This example uses the TApplication and TDocument 


g 
8 
tt 
t 
tt 
8 classes defined in the Apple С++ examples 
tt 


8--------------:/ 


*include 
Sinclude 
8include 
* include 
*include 
*include 
*include 
8include 
*include 
*include 
*include 
include 
* include 
*include 
*include 
8include 
Sinclude 
Sinclude 
Sinclude 


«Types. h? 
<QuickDraw.h> 
«Fonts.h? 
«Events.h? 
<OSEvents.h> 
«Сопіго16.һ» 
«Мілдон5.һ» 
«Menus .h> 
(TextEdit .n» 
«Dialogs.h? 
«Desk. h? 
<Scrap.h> 
«ToolUtils.h» 
«Memory.h? 
«SegLoad.h» 
«Files.» 
<OSUtils.h» 
«Traps .h> 
<StdLib.h»> 
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// Constants, resource definitions, etc. 
Sdefine kMinSize 48 // min heap needed in К 


Sdefine rMenuBar 128 /* application” 's menu bar */ 
def ine rAboutAlert 128 /* about alert */ 
Sdefine rDocWindow 128 /Х application’s window */ 


“define mApple 128  /* Apple menu */ 
define iAbout 1 


def ine mFile 129 /* File menu */ 
"define iNew 1 

Sdefine iClose 4 
Sdefine iQuit 1 


8def ine mEdit 130 /* Edit menu */ 
8Sdef ine iUndo 1 
Sdefine iCut 3 
8def ine iCopy 4 
"define iPaste 5 
"define iClear 6 


Sdefine myMenu 131 /* Sample menu */ 
Sdefine item! l 
Sdefine item2 2 
Sdefine items 3 
Sdefine itemd 5 


include “TDocument.h” 
include “TApplication.h” 
“Чілсімде “MacTutorApp.h” 


// create and delete document windows 
// call initializer of base class TDocument 
// with our window resource ID 
TMacTutorDocument: : TMacTutorDocument 

(short resID, StringPtr s) : CresID) 


SetDisplayString(s); 


ShowWindowCfDocWindow2;// Make sure the window is visible 


TMacTutorDocument : :~TMacTutorDocument(void) 


HideWindowCfDocWindow); 


void TMacTutorDocument : :DoUpdate(void) 


BeginUpdateCfDocWindow); 
if С ! EnptyRgnCfDocWindow- visRgn) ) 
// draw if updating needs to be done 
DrawWindowC); 


EndUpdate(fDocWindow); 


// Draw the contents of an application window. 
void TMacTutorDocument: :DrawWindowCvoid) 


SetPortCfDocWindow); 
EreseRectC&fDocWindow-?portRect); 


MoveTo( 100, 100): 

TextSize(18); TextFont(monaco); 
. DrawString(fDisplauString); 
) // DrawWindow 


// Methods for our application class 
b аа 
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// this sets up the visRgn 


Handle menuBar ; 


// read menus into menu bar 

menuBar = GetNewMBar (rMenuBar ); 

// install menus 

Se tMenuBar (menuBar ); 
DisposHandle(CmenuBar?; 

// add DA names to Apple menu 
AddResMenu(GetMHandle(mApple), ‘DRVR’); 
DrawMenuBar C ); 


// create empty mouse region for MouseMoved events 
fMouseRgn = NewRgn(); 

// create a single empty document 

DoNew( ); 


// Tell TApplication class how much heap we need 
"a TMacTutorApp: :HeapNeeded(void) 


return (kMinSize * 1024); 


// Calculate a sleep value for WaitNextEvent. 
// method proposed in the Apple example 


(me long TMacTutorApp: :SleepVal(Cvoid) 


unsigned long sleep; 

const long kSleepTime = OxTfffffff; 

Sleep = kSleepT ime; // default value for sleep 
if (C!fInBackground2) 


sleep = GetCaretTime(); 
// A reasonable time interval for MenuClocks, etc. 


return sleep; 


void TMacTutorApp: :AdjustMenus( void) 


WindowPtr frontmost; 
MenuHandle menu; 
Boolean undo, cutCopyClear, paste; 


TMacTutorDocument* fMacTutorCurDoc = 
(TMacTutorDocument*) fCurDoc; 
frontmost = FrontWindow(); 


menu = GetMHandle(mFile); 
if С fDocList-»NumDocsC) < kMaxOpenDocuments ) 


EnableItem(menu, iNew); // New is enabled when we can 
open more documents 


else DisableItem(menu, iNew); 

if С frontmost != CWindowPtr) nil ) 
// is there a window to close? 
Enableltem(menu, iClose); 

else DisableItem(menu, iClose); 


undo = false; cutCopyClear = false; paste = false; 


if ( fMacTutorCurDoc == nil ) 
( 


undo = true; // all editing is enabled for DA windows 


cutCopyClear = true; 
peste = true; 


menu = GetMHandle(mEdit); 
if С undo ) Ena&blelItem(menu, iUndo); 
eise DisableItem(menu, iUndo); 


if С cutCopyClear ) 
( Enableltem(menu, iCut); 
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Enableltem(menu, iCopu); 
Enableltem(menu, iClear); 


else 
( Disableltem(menu, iCut); 
Disableltem(menu, iCopu); 
Disableltem(menu, iClear); 


if С paste ) Enableltem(menu, iPaste); 
else Disableltem(menu, iPaste); 


menu = GetMHandle(muMenu); 
Enableltem(menu, item1); 
Enableltem(menu, item2); 
Enableltem(menu, item3); 
Enableltem(menu, item5); 


CheckItem(menu, item1, false); 
CheckItem(menu, item2, false); 
CheckItem(menu, item3, false); 
CheckI tem(menu, item5, false); 
CheckI tem 
(menu, fMacTutorCurDoc->GetI temSelected(), true); 
) // AdjustMenus 


void TMacTutorApp: :DoMenuCommand 
(short menuID, short menul tem) 
( 


short itemHit; 

Str255 daName; 

short daRefNun; 

WindowPtr window; 

TMacTutorDocument* fMacTutorCurDoc = 
(TMacTutorDocument*) fCurDoc; 

window = FrontWindow(); 

ad € menuID ) 


case mApple: 
“= С menultem ) 


case iAbout: // About box 
itemHit = AlertCrAboutAlert, nil); break; 
default: // DAS etc. 
GetI tem(GetMHandle(mApple), menuItem, daName); 
ЖА = OpenDeskAcc(daName); break; 


break; 
case mFile: 
switch C menultem ) 


case iNew: DoNew(); break; 
case iClose: 
і? (fMacTutorCurDoc != nil) 


fDocList-»RemoveDocCfMacTutorCurDoc); 
delete fMacTutorCurDoc; 


else CloseDeskAcc 
(((WindowPeek) fWhichWindow2- windowK ind); 
break; 
case iQuit: Terminate(); break; 


break; 


case mEdit: // call SustemEdit for DA editing & MultiFin- 


der 
1f С !SustemEdit(menultem-1) ) 


switch ( menultem ) 
case iCut: break; 
case iCopy: break; 


case iPaste: break; 
case iClear: break; 
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) 


break; 
case muMenu: 
C (fMacTutorCurDoc != nil) 


ыы ( menuItem ) 


case itemi: 
fMacTutorCurDoc- SetDisplayStringC^MpC** ^); 
break; 
case item2: 
fMacTutorCurDoc-?SetDisplayStringC^MpSample^); 
break; 
case items: 
fMacTutorCurDoc->SetDisplayStr ing(“\pApplication”); 
break; 
case item: 
fMacTutorCurDoc->SetDisplayStr ing(”\pHave Fun”); 
break; 


fMacTutorCurDoc->SetI temSelected(menul tem); 
InvalRect(&window-) por tRect); 
айын 


break; 


) 
HiliteMenu(o); 
) // DoMenuCommand 


// Create a new document and window. 
"n TMacTutorApp: :DoNewCvoid) 


TMacTutorDocument* tMacTutorDoc; 
tMacTutorDoc = new TMacTutorDocument 
(rDocW indow, "M5pNothing selected yet. ^); 
// if we didn’t get an allocation error, add it to list 
if (tMacTutorDoc != nil) 
fDocL ist-» AddDoc( tMacTutorDoc); 
) // DoNew 


void TMacTutorApp: : TerminateCvoid) 


ExitLoop(); // exits the main event loop 


// Our application object, initialized in main(). 
TMacTutorApp *gTheApp] ication; 


// main is the entrypoint to the program 
C nain(void) 


// Create our application object. 
// This also initializes the Toolbox - 
gTheApplication = new TMacTutorApp; 


if C(gTheApplication == nil) // if we couldn't allocate 


object Cimpossible!?) 
return £; // go back to Finder 


// Start main event loop 
gTheApp]ication->»EventLoop(); 


// return some value 
return 0; 
) 


Listing 2: MacTutorApp.h - class definitions 


// Class definitions. 


// Our document class. 

// Only displays some text in a window 

// 

class TMacTutorDocument : public TDocument ( 
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private: 

short fltemSelected; 

// string corresponding to menu item selected 
StringPtr fDisplauString; 


void DrawWindow(void); 


public: 

TMacTutorDocument(short resID, StringPtr s); 

“TMacTutorDocument(void); 

// routine to access private variables 

void SetDisplauString (StringPtr s) 
(fDisplayString = s;) 

short GetItemSelected(void) feturn fltemSelected;) 

void SetItemSelected(short item) 
(fItemSelected = item;) 

// methods from TDocument we override 

) void DoUpdate(void); 


// TMacTutorApp: our application class 
class TMacTutorApp : public TApplication ( 
public: 

TMacTutorApp(void); // Our constructor 


private: 
// routines from TApplication we are overriding 
long HeapNeeded(void); 
unsigned long SleepVal(void); 
void AdjustMenus(void); 
void DoMenuCommand (short menuID, short menuItem); 
// routines for our own purposes 
void DoNewCvoid); 
void TerminateCvoid); 


); 
const shortkMaxOpenDocuments = 1; 


Listing 3: MacTutorApp.r - 
Rez input for our program 


"include "SysTypes.r"^ 
"include *Types.r^ 


"define kPrefSize 60 
"igef ine kMinSize 48 


"define kMinHeap (34 * 1924) 
define kMinSpace (20 * 1024) 


/* id of our STR" for specific error strings */ 
"define kMacTutorAppErrStrings 129 


/* Indices into STR® resources. */ 
8define eNoMemory 1 
"def ine eNoWindow 2 


8def ine rMenuBar 128  /* application’s menu bar */ 
define rAboutAlert128 /% about alert */ 
"define rDocWindow 128 /% application’s window */ 


"define mApple 128 /* Apple menu */ 
"define iAbout 1 


"define mFile 129 /* File menu */ 
Sdefine iNew 1 

Sdefine iClose 4 

define iQuit 12 


"define mEdit 130 /* Edit menu */ 
#define iUndo 1 
define iCut 3 
"define iCopy 4 
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"define iPaste 5 
"define iClear 6 


"define myMenu 131 /* Sample menu */ 
define item! 1 
"define item2 2 
"define item3 3 
"define itemd 5 


resource ‘vers’ (1) ( 
8x01, 0х00, release, 0x00, 
verUS, 
* 1.00", 
“1.08, Copyright € 1989 J. Langowski / MacTutor” 


resource ‘MBAR’ (rMenuBar, preload) ( 
( mApple, mFile, mEdit, myMenu ); 


, 


resource ‘MENU’ (mApple, preload) ( 
mApple, textMenuProc, 


0b1111111111111111111111111111101, /* disable dashed line, 


enable About and DAs */ 
Co apple, 


“About CPlusMacTutorApp..”, 
noicon, nokey, nomark, plain; 
“-", noicon, nokey, nomark, plain 


); 


resource ‘MENU’ (mFile, preload) ( 
mFile, textMenuProc, 


0b0000000000000000000 100000000000, /* program enables 


others */ 
enabled, "File", 


“Мен”, noicon, "N^, nomark, plain; 
“Open”, noicon, “0”, nomark, plain; 
*-*, noicon, nokey, nomark, plain; 
“Close”, noicon, “W?, nomark, plain; 
“Save”, noicon, "S^, nomark, plain; 
“Save As..”, noicon, nokey, nomark, plain; 
“Revert”, noicon, nokey, nomark, plain; 
*-^, noicon, nokey, nomark, plain; 
“Page Setup..”, noicon, nokey, nomark, plain; 
“Print..”, noicon, nokey, nomark, plain; 
*-", noicon, nokey, nomark, plain; 
“Quit”, noicon, *Q^, nomark, plain 
) 
); 


resource ‘MENU’ (mEdit, preload) ( 
mEdit, textMenuProc, 


000000000000000000000000000000000, /% program does the 


enabling */ 
aes “Edit”, 


“Undo”, noicon, “Z?, nomark, plain; 
*-^, noicon, nokey, nomerk, plain; 
*Cut^, noicon, *X^, nomark, plain; 
*Copy^, noicon, "C^, nomark, plain; 
“Paste”, noicon, *V^, nomark, plain; 
“Clear”, noicon, nokey, nomark, plain 
) 
); 


resource ‘MENU’ (myMenu, preload) ( 
myMenu, textMenuProc, 
0b0000000000000000000000000000000 , 
enabled, “Strings”, 


“C++”, noIcon, nokey, noMark, plain, 
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“Sample?, noIcon, nokeu, noMark, plain, 
“Application?, nolcon, nokeu, noMark, plain, 
*-^, nolcon, noKeu, noMark, plain, 
“Have Fun”, noIcon, nokey, noMark, plain 
); 


/* the About screen */ 
resource ‘ALRT’ CrAboutAlert, purgeable) ( 
(40, 20, 198, 360 ), rAboutAlert, ( 
OK, visible, silent; 
OK, visible, silent; 
OK, visible, silent; 
OK, visible, silent 


Pa 


); 
resource ‘DITL’ (rAboutAlert, purgeable) ( 


(120, 240, 140, 320), 
Button ( enabled, “OK” ), 


(8, 8, 24, 320 ), 
StaticText ( disabled, 
“MacTutorApp: C++ nini-application Skeleton" ), 


(32, 8, 48, 320), 
SteticText ( disabled, 
“Copyright € 1989 J. Langowski / MacTutor” ), 


(56, 8, 72, 320), 
Staticlext. ( disabled, 
“(Based on examples by Apple MacDTS]”?), 


(80, 8, 112, 320), 
StaticText ( disabled, 
“Expand this application to uour own taste” ) 


); 


resource ‘WIND’ (rDocWindow, preload, purgeable) ( 
(64, 60, 314, 460), 
noGrowDocProc, invisible, goAway, 0х0, 
*MecTutor C++ demo” 


9 


шайы ‘STR®’ (kMacTutorAppErrStrings, purgeable) ( 


“Not enough memory to run MacTutorApp?; 
y en create window”; 


); 


resource ‘SIZE’ (-1) ( 
dontSaveScreen, acceptSuspendResumeEvents, 
enableOptionSwitch, canBackground, 
multiFinderAware, backgroundAndForeground, 
dontGetFrontClicks, ignoreChildDiedEvents, 
is32BitCompatible, 
reserved, reserved, reserved, reserved, 
reserved, reserved, reserved, 
kPrefSize * 1024, kMinSize * 1024 

); 


type “JLMT” as ‘STR '; 
resource ‘JLMT’ (0) C 

"MacTutor C++ Sample Application” 
resource ‘BNDL’ (128) ( 

'JLMT^, 0, 


‘ICN®’, (0, 128 ), 
'FREF^, (0, 128 ) 


244 


) 


); 
resource ‘FREF’ (128) ( 


‘APPL’, Ø, “” 


. 
д 


resource ‘ICN®’ (128) ( 


( /* MacTutor - JL ICN® */ 
/* (1) */ 


%%00 01 80 00 00 07 Ей 00 00 IF FB 00 00 TF FE 00" 
%%01 FF FF 80 07 FF FF Ей OF FF OF FB 07 FF 33 FC" 
$°03 FF FC 38 06 FF FF CB 0С ЗЕ FF FE 08 OF FF 06" 
%%08 03 FF 96 08 FO FF 19 09 FB ЗЕ 16 09 88 ØC 19" 
%%08 00 00 16 08 00 00 10 ØB IE 78 00 OB FF FF 00" 
$^09 FF FF 90 FC ТЕ ТЕ ЗЕ 96 00 00 бА ОЗ FF FF СА? 
$752 00 00 АА 53 FF FF CB Аб 38 70 69 DC 44 88 3F” 
$^1Е 38 73 98 38 87 04 4C 67 08 83 86 ТЕ FF FF FE”, 
/* [21 */ 

%%00 07 Ей 00 00 IF F8 00 00 ТЕ FE 00 01 FF FF 80" 
$°07 FF FF Ей ІҒ FF FF FB ІҒ FF FF FC OF FF FF РЕ” 
%%07 FF FF FC 07 FF FF ЕВ ØF FF FF FE OF FF FF FE" 
$"0F FF FF FE OF FF FF FF OF FF FF FE OF FF FF FF” 
$^üF FF FF F6 OF FF FF FO ØF FF FF FO OF FF FF FO" 
$°0Е FF FF FØ FF FF FF FE F7 FF FF EE ЕЗ FF FF СЕ” 
$°73 FF FF CE 73 FF FF CF ЕТ FF FF EF DF FF FF ҒҒ” 

F FF FE FF FF FF FF FF FF FF FF” 


x FF FF ЕВ ТЕЕ 


); 

Listing 4: MacTutorApp.make - the make file 
? File: MacTutorApp.make 

# Target: MacTutorApp 

*? Sources: MacTutorApp.cp 

8 MacTutorApp.h 

н MecTutorApp.r 

8 TApplication.cp 

a TApplication.h 

Li TDocument .cp 

8 TDocument.h 

8 TApplication.r 

8 Created: Wednesdau, October 18, 1989 8:15:31 
OBJECTS = 9 


MacTutorApp.cp.o TApplication.cp.o TDocument.cp.o 


MacTutorApp.cp.o f д 


T 


MacTutorApp.make MacTutorApp.cp MacTutorApp.h 
CPlus MacTutorApp.cp 
Application.cp.o f à 
MacTutorApp.meke TApplication.cp TApplication.h 
CPlus TApplication.cp 


TDocument.cp.o f à 


MacTutorApp.make TDocument.cp TDocument.h 
CPlus TDocument.cp 


MacTutorApp ff MacTutorApp.make (OBJECTS) 


Link -w -t APPL -c JLMT à 
* (CLibreries)"CRuntime.o à 
(OBJECTS) à 
* (Libraries)^Interface.o д 
* (CLibreries)^"StdCLib.o à 
* (CLibreries)^CSANELib.o 9 
* (CLibraries)"Math.o д 
* (CLibreries)^CInterface.o д 
“(CLibraries}*CPlusLib.o à 
9“ (CLibreries)"Complex.o à 
-o MacTutorApp 


MacTutorApp ff MacTutorApp.make MacTutorApp.r 


Rez MacTutorApp.r -append -o MacTutorApp 


MacTutorApp ff MacTutorApp.make TApplication.r 


Rez TApplication.r -append -o MacTutorApp 


sel 


cian 
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Pascal 
Procedures 


Pascal Procedures 
Finder Icon Controls 


Finder-like icon-tontrols 
How to write, debug and use 'MDEF' and ‘CDEP’ 
resources. 

Jean de Combret is a former river-hydraulics engineer, who 
worked with mathematical models human-unfriendly programs. 
He thinks the Mac could be a solution to make such programs 
more friendly and has therefore set up “Diadéme Ingénierie" 
and written "ONDULA" . He is a member of "Macintosh Alpes 
Club", as well as Didier Guillon, Jórg Langowski [hum... 
thanks! -JL] and a lot of other interesting folks. 


Introduction 
While developing my application, it appeared to me I needed 
an object-interface, somewhat like the Finder's one, with icons, 
hierarchy (folders contain other icons), actions (by double- 
clicking, classifying, throwing away or choosing in a menu). So 
Idecided to write my own objects, and the best way I found to do 
it was to make them user-controls. 
VarCodes 
All icons of the family I've created bear the same appear- 
ance: an icon, and an underlying name. But each member of the 
family has different properties, which may be done by giving 
different *varCodes" to each variant. I choose a system of 
additive varCodes, although not all combinations have sense: 
moveablez1; 
means the control may be dragged inside its window (like all 
icons in the Finder); 
doubleClickable=2; 
means the control may generate an action by double-click- 
ing it: it should then take an “open” appearance (like folders, 
disks and trash icons that generate a window, or like application 
icons that start-up applications); 
trash=4; 
means the control may “swallow up” another one released 
over its head. It should highlight while the mouse, dragging the 
control to be swallowed up, is still down and pointing to it (like 
trash, folders and disks icons in the Finder) 
menu=8; 
is a new type of control icon I’ve imagined : it should 
generate a pop-up menu of icons when pressed. This is an 
alternate technique to the palette menus and tear off menus. The 
menu is by the way bound to a window. 
Some examples of possible combinations are listed below: 
• a folder would be declared “movable + doubleClickable + 
trash” and its varCode would therefore be 7; 
* a growing menu of icons would be “menu + trash” i.e. 12 
(*menu" for removing or choosing items, “trash” to add 
items); 
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• ап application icon would be declared “movable + double- 
Clickable" i.e. 3. 

In fact, “menu” is exclusive of “movable” or “doubleClick- 
able". 

Menu definition procedure and pop-up menus 

Before building our custom control definition procedure, we 
must first build our custom icons menus. At that point, the two 
first problems are 

° to write a " MDEF' code resource ; 
* to make it work with pop-up menus. 

Inside Macintosh indicates p.I-362 how to write * MDEF's 
for pull-down menus. In my alpha release of the fifth volume (for 
which the French Macintosh Development Support failed to send 
me updates), I don't find anything about pop-up menus nor about 
custom menus. I just found two significant pieces of information 
in the Color Menu Manager interface in my LightSpeed Pascal 
libraries -a new trap declared as 


PROCEDURE PopUpMenuSelect (menu : MenuHandle; 
top , left , popUpItem : INTEGER) : LONGINT; 
inline $4808; 


and a constant : 


mPopUpMsg=4; ( sic ) 

This latter statement appeared later to be false. I learned by 
disassembling the standard code resource ‘MDEF’ 0 of the new 
system file, that only values ranging from 0 to 3 are accepted as 
messages, and that the one corresponding to pop-up menu 
treatments is 3: 

mPopUpMsg=3; ( right value ) 

By the way I learned that the routine responds to this new 
message by calculating “menuRect”, given “menu”, “top”, “left” 
and “popUpltem” parameters of PopUpMenuSelect transmitted 
respectively through the “theMenu”, “hitPt” and “whichItem” 
parameters from the menu definition procedure declaration : 


PROCEDURE MyMenu (message : 
theMenu : MenuHandile; 
VAR menuRect : Rect; 
hitPt : Point; 


VAR whichItem : 


INTEGER; 


INTEGER); 


Since I wrote most of this article, all of this has been 
confirmed by TechNote #172 from the November 1987 release. 
It just took 6 months to get it! 

Before getting TechNote #172, I wasn't quite sure I hadn't 
made a mistake, but now I' m sure: hitPt is not a point! Instead it 
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receives “left” and “top” inverted from PopUpMenuSelect. 

I also tried the trap with standard text menus. The two hints 
Ishallgive follow: ( Ifound the secondby decompiling the ROM 
patches; next time ГІ first have a look to Inside Macintosh 
p.351!) 

° pass -1 as beforeID parameter to InsertMenu (the same as 
for hierarchical menus) to indicate that theMenu is in the current 
menu list, but is not to be drawn in the menu bar. 

° pass a positive non-zero integer as MenuID to NewMenu 
or nothing will ever appear on the screen (you may also store it 
in the ‘MENU’ resource read by GetMenu, of course). 

Debugging A Code Resource (Part 1) 

I shall indicate two techniques to test and debug code 
resources under LightSpeed Pascal. The first one, used here, is 
the roughest and should never be used for anything else than 
debugging. I learned the second one from the best Macintosh 
programming journal I know (I mean the April issue of MacTutor 
p.17 and p.30), and I should give an example of the use I made 
of it further in this article. 

The problem is to access and debug the source text of acode 
resource while running a shell program that calls it via Menu 
Manager routines (or Control Manager routines for ‘CDEF’s). 
Normally the code resources is compiled separately and accessed 
through a handle to the ‘MDEF’ resource. The Menu Manager 
routines use to lock the ‘MDEF’ resource upon entry, derefer- 
ence the handle, jump to its beginning and unlock it upon exit. 

My technique consists in declaring the unit with the 'ÁMDEF"' 
source text in the uses statement of a small debugging-purpose 
shell program, and I create a new menu as follows: 


myMenu := GetMenu( 128); 
myProcPtr := @main; 
myMenu**.menuProc := @myProcPtr ; 


This way, the handle and its dereferenced pointer point to the 
Stack, not at a masterpointer or a block within the heap. The 
HLock and HUnLock procedures may act on the high order bit 
of these pointers, it has no influence on the addresses (neverthe- 
less be aware of TechNote #2 item 11). The Memory Manager 
never knows about the block and never tries to move it. 

With this trick, you may freely use all the debugging facili- 
ties of LightSpeed Pascal: the Observe and LightsBug windows, 
the Step mode... 

Once all the bugs inside the ‘MDEF’ code have been fixed 
(or at least seam to), you build your ‘MDEF’ code resource. I 
gave mine a ResID of 128. Under ResEdit, you can see that the 
compiler gave to this resource a default attribute “purgeable”, 
you'd never ask it to give. Instead I changed it to “locked” and 
“preload”, in order to have it always under the hand (a disk access 
while pulling a menuis not user-friendly) and to keep itin the low 
region of the application heap. 

New Meaning of ‘MENU’ Resource 

The '*MDEF' and 'CDEF' are not the only user resources I 
wrote for my application. I like the flexibility of building all sort 
of data resources as well as compiling code resources. In the 
current example, my menu consists of icons, described by their 
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names and their positions in the menu rectangle. It's slightly 
different from the standard ‘MENU’ resource information. But 
in order to use the Menu Manager routines, I preferred interpret- 
ing the same ‘MENU’ resources in a different way, rather than 
create a completely new resource type. Description of the re- 
source format given p.I-364 of Inside Macintosh should be 
replaced by : 


Number of bytes Contents 


2 bytes Menuld 

2 bytes Placeholder for menu width 

2 bytes Placeholder for menu height 

2 bytes Resource ID of ‘MDEF’ 

2 bytes Place holder for ‘MDEF’ handle 
4 bytes EnableFlags 

п+1 bytes Title as Pascal string 


for each menu item : 


m+1 bytes Text of item as Pascal string 

2 bytes Vertical coordinate of icon center 
2 bytes Horizontal coordinate of center 

1 byte 0, indicating end of menu items 


(it is also a Pascal null string) 


Note that this description occupies the same number of bytes 
that normal text menus do, which ensures the ability to use the 
standard procedures. 

This description is almost the same as the one you can teach 
to ResEdit; I created anew ‘TMPL’ resource in the ResEdit file 
itself, which I gave the name ‘MPOP’. However, in order to use 
the GetMenu routine, my menu resources shall not be of type 
‘MPOP’ but of type ‘MENU’. This is accomplished by creating 
а new ‘MENU’ resource and opening it with the “Open as...” 
command to indicate we wish to use the *MPOP' format instead 
of the ‘MENU’ one to edit our resources (shortcut for “Open 
as...” is shift-option-double-clicking). 

The “TMPL’ resource describes the structure of the “МРОР” 
resource, somewhat like a Pascal record type describes the 
structure of a Pascal record variable (for more details see the 
MPW chapter about ResEdit) : 


Label Type 
MenuID DWRD 
width DWRD 
height DWRD 
procID DWRD 
filler DWRD 
enableFlags — HLNG 
title PSTR 
ak 3k k k k LS TZ 
menultem PSTR 
center.v DWRD 
center.h DWRD 
Sk sk kk k LSTE 
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Reading A Resource 

In fact this new syntax allowed by ResEdit gives more 
generality and compactness than Pascal records do: strings in 
Pascal records always occupy 256 bytes in memory, even if only 
10 are actually used. Consequently, Pascal is not able to decipher 
such resources. So I had to write some inline assembly routines 
for this purpose. These routines read a chosen type beginning at 
a given address that might be odd and return a Pascal formatted 
value on the stack. For strings it returns a StringHandle on the 
stack, pointing to a string of the actual size in the heap. I give here 
three of these inline routines : 


FUNCTION GetNextByte 
(VAR LongAddress : LONGINT) : BYTE; 


FUNCTION GetNext Integer 
(VAR LongAddress : LONGINT) : INTEGER; 


FUNCTION GetNextStr ing 
(VAR LongAddress : LONGINT) : StringHandle; 


These functions return NIL if allocation failed. 

For each of these routines LongAddress is incremented by 
the amount of bytes read. 

The same routines in Pascal would have called BlockMove, 
which is very efficient for larger blocks but far too long for such 
a few bytes. 

As an example, here is what GetNextB yte would look like in 
Pascal : 


FUNCTION GetNextByte (VAR longAddress : LONGINT) : BYTE; 

VAR result : BYTE; 

BEGIN 

result := 0; 

BlockMove(POINTERC longAddress), POINTERCORDCéresult ) + 1), 

1); 
GetNextByte := result ; 
longAddress:= longAddress* 1; 


END; 
I added some other Pascal utilities for easy reading and 
writing : 


FUNCTION SkipNextString (VAR LongAddress : LONGINT) : BYTE; 


PROCEDURE SkipBytes (VAR LongAddress : LONGINT; byteCount : 
INTEGER); 


Routines and Messages 

Let's come to our central topic: the control definition proce- 
dure. First of all note that there are 9 messages to the “СЕРЕ” code 
instead of only 4 tothe * MDEF' code. Controls are more complex 
than menus and hence more versatile. 

I find Inside Macintosh not systematic enough in describing 
the meanings of these messages and I don't know other informa- 
tion about them. So I decided to build my own complete table of 
what messages each routine of the Control Manager sends to the 
*CDEF' code. I wrote a small program to help me in this task by 
installing a spy a the entry of the “СЕР” code. Figure 1. shows 
the table resulting from this spying. 
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etNewControl 


KillControls calcCRgns 
dispCntl 


calcCRgns 
drawCntl 


TrackControl 
(otherwise) 


DragControl 
calcCRgns 
drawCntl (=MoveControl) 
drawCntl 


SetCtiValue _ |drawCntl J — ^  — 
E 
ЕЕЕ 


SetCtIMin 
SetCtiMax |ЯШамбпі/ | 


Fig. 1: messages sent by the Control Manager 
routines 


The program I used is listed below and I shall give here some 
explanations about the way I installed my spy, because it involves 
the second technique of building ‘CDEF’ resources from the 
same source file than the host program. 

Debugging a Code Resource (Part 2) 

Here comes the clean way of doing it (Thanks to Larry 
Rosenstein and also to Don Melton and Mike Ritter for the basic 
idea). You create a 6-byte handle and put a JMP $xxxxxx 
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instruction in the block, which jumps to your procedure. Then 
you declare this block as a ‘CDEF’ resource which you give an 
unused ID. Then you can pass this ID to NewControl : 


TYPE 
CDEFcodeHdl = *CDEFcodePtr; 
CDEFcodePtr = *CDEFcodeRecord; 
CDEFcodeRecord = RECORD 
jump : integer; 
address : ProcPtr; 
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VAR muControl : ControlHandle; 
myCDEF : CDEFcodeHd1; myCDEFid : integer; 


FUNCTION ControlDefProc (varCode : INTEGER; 
theControl : ControlHandle; message : INTEGER; 
param : LONGINT) : LONGINT; 

BEGIN 
( put here the source of the ‘CDEF’ ) 


, 


BEGIN ( here begins your host program ) 
myCDEF := CDEFcodeHd] (NewHandle(6)); 
myCDEF**. jump := $4EF9; 
myCDEF** address := @ControlDefProc; 
myCDEFid := UniqueIDC'CDEF ^); 

AddResourceChandle(myCDEF), ‘CDEF’, myCDEFid, 77); 


, 
( XXXXXXxx*xxxxxxxxxxxxxxxoeek ) 


( write here the inits of your host program ) 
( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖ 


muControl := NewControlCtheWindow, boundsRect, title, 


visible, value, min, max, myCDEFid * 16 + varCode, refCon); 
( XXXKXXXXX1XXXIXXXXXXXXKKXXXXXKX ) 


( write here the body of your host program ) 
( KXXKXXXXIXXXXXKXXXFXIXKXXXKXXXXKXKXEX ) 


бізрозеСоліго1(туСоліго1); 
RmveResource(handle(muCDEF)); 


DisposHandle(handle(muCDEF)); 
( XXXXKXXXXX1XXXXXKXIXXXXKKXXXXXXEXKXEK ) 


( write here the disposals of your host program ) 
( ХХХХХХХХХХХХХХХХХХХХХХХЖХХХЖХХЖ ) 


END. 

For more information, you'll have to refer to the listing given 
below (e.g. : don’t have a too large UniqueID, it must be less than 
maxint DIV 16 ...). 

Another interesting technique is the way of using routines 
passed by address from Pascal. Although Inside Macintosh says 
p.I-78 “Only routines written in assembly language ... can 
actually call the routine designated by a pointer of type ProcPtr”, 
it’s very easy to write inline code to do the job within Pascal 
programs. Suppose you have this function declaration : 


FUNCTION MyFunction CfirstArg : firstType; 
secondArg : secondType; 
VAR thirdArg : thirdType) 


: resultType; 

If you want to call it by address (given by @ MyFunction, or 
by a handle if the function is compiled as a code resource) you 
must declare an inline glue function. 

For a function passed by pointer it should be : 


FUNCTION CallMyFunction CfirstArg : firstType; 
secondArg : secondType; 
VAR thirdArg : thirdType 


MyFunctionAddress : ProcPtr) : resultType; 
INE 
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$205F, 
$4E90; 


(MOVE.L 
(JSR (A0)) 


CA7)+, AO) 


or, for a function passed by handle (after having locked it): 


FUNCTION CaliMyFunction (firstArg : firstType; 
secondArg : secondType; 
VAR thirdArg : thirdType 
MyFunctionResource : handle) : resultType; 
INLINE 
$205F, (MOVE.L CA7)+,A0) 
$2050, (MOVE.L CA0),A0) 


$4Е90; (JSR (A02) 


As you can see the declaration is exactly the same as in the 
original function, except that we add one last parameter. This 
technique applies as well to procedures. The number of argu- 
ments doesn't matter, only matters the coherence between the 
two declarations. 

Coming back to our example, you'll notice a supplementary 
line in the inline code of my program, because tracing the 
‘CDEF’ resource with MacsBug showed that it relied on а 
function return value being previously cleared. 

Implementing the Control Definition Procedure 

My goal was to do as much work as possible within the 
"CDEF" code, in order to simplify the end programmer's job of 
writing the host program. 

Although "movable" controls should act through the 
DragControl routine, I grouped all actions of all the variety of 
controls under the TrackControl routine. I implement also cus- 
tom initializations and disposals. 

Here follows descriptions of : 

* what the ControlRecord fields are used to ; 
* how the control definition procedure responds to each 
message ; 
* how to use the Control Manager routines to make my 
controls work correctly. 
ControlRecord fields 
° ContriTitle contains the name that is used to find the related 
resources such as ‘ICN#’ and ‘MENU’. 
° in order to speed up memory access to the icon and menu 
records related to the control, I store handles to them in the 
following structure : 


TYPE 
DataHandle = *DataPointer; 
DataPointer = ^DateRecord; 
DataRecord = RECORD 
theIcon : handle; 
theMenu : MenuHandle; 


END; 


and I store the DataHandle in the ContrlData field. 
° I use the ContrlRefCon field to store the values returned from 
the ‘CDEF’ routines : 
- the ControlHandle of the “trash” in case the current control 
has been put in it; 
- the choice made from the icon menu, as returned by 
PopUpMenuSelect. 
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• ContrlHilite is not used. 

• I use 6 levels of Contri Value ranging from ContriMin = 0 to 
ContrIMax = 5. Rather than a continuous scale, they corre- 
spond to six different states of the controls (the “ContrlHil- 
ite" field could have been used for the same purpose): 


This is the data of my icon (of type 
‘ICN#’) 


This is its mask. 


RestState=0; 
(same as the data on white background) 


SelectState = 1; 


Er OpenState = 2; 


SelectOpenState z 3; 


Technical note #55 describes how the Finder draws icons in 
that variety of ways. But in fact it’s not the actual way the old and 
new Finders do it. I think my algorithm is closer to reality. I’ve 
studied it using a funny feature of MacsBug -the Step Spy 
command : 

SS 400000 400000 

that slows all 68xxx instructions, and is specially recom- 
mended to examine graphical aspects of an application. 


*CDEF' Routines in Response to the Messages 

° drawCntl : draws the control with its title and its icon 
according to the state (i.e. its ContrIValue) ; 

° testCntl : tests if the point is inside the icon’s data or mask ; 

* calcCRgns : calculates the region, union of the rectangles 
enclosing the icon and the title. This region is used for any 
erasing of the control and updating of the underlying pixels, 
or for drawing the dotted outline when dragging the control 


e initCntl : stores the handles to the icon and to the menu in a 
structure, pointed to by another handle which is in turn 
stored in the ContrlData field, and sets the actionProc 
parameter to POINTER(-1), to indicate we implement a 
custom autoTrack routine ; 

e dispCntl : disposes the ContrIData handle but not the icon and 
menu handles which are resources and may be shared by 
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other controls ; 

° posCntl : not used, because my controls don't have any 
indicator ; 

° thumbCnt : not used ; 

e dragCntl or autoTrack : the most important routine. First it 
sets the control to a selected state and deselects any other 
currently selected control. Then, if the control is “movable”, 
it detects the movements of the mouse,pulls a dotted outline 
and highlights the trashes the control flies over. If it was 
actually moved, it invalidates regions to be updated. If it was 
released over a "trash", its value is set to 4 and the trash's 
ControlHandle is returned in ContrlRefCon. Then it looks 
for a double-click in case the control is “double-clickable” 
and hasn’t been moved. In the other case where the control 
is a “menu” control, the routine generates the pop-up menu, 
by calling PopUpMenuSelect as described above and re- 
turns the choice іп ContrlRefCon. 

Note that a small problem arises in these routines when they 
callin turn other routines of the Control Manager -when the latter 
returns, the ‘CDEF’ resource is unlocked by the Control Man- 
ager, although the next instructions are still in the *CDEF'. So it 
is imperative to re-lock the ‘CDEF’ resource after each call to the 
Control Manager within the ‘CDEF’. If Apple had used HGet- 
Sate / HSetState instead of HLock / HUnLock to bracket the calls 
to 'CDEF', I think this problem would not exist. 

Note also I let the user access to this last routine by two ways 
: TrackControl, which is more logic, and DragControl that calls 
“drawCntl” only when necessary, as shows figure 1., and thus 
makes a cleaner interface. 


Control Manager Routines User’s Guide 
Here is the way the standard routines act on my custom 
controls: 

• NewControl ог GetNewControl are used to create the con- 
trols with the following values of the parameters : 

- boundsRect set to the 32x32 icon's rectangle ; 
- maxz 5; 
- min z0; 
- procID = 128 * 16 + varCode ; 
- title = *CNTL” resource name 
= ‘ICN#’ resource name 
= ‘MENU’ resource name ; 

° TrackControl is used to make the controls work properly. 
Pass POINTER(-1) as actionProc, in order to let the Control 
Manager generate autoTrack messages. 

eDragControl is used for the same purpose (see above). Pass 
anything as bounds, slop and axis. 

* GetCRefCon is used to get the choice returned from the pop- 
up menu or the handle to the “trash” the current control was 
put in ; 

e SetCtlValue is used to close icons : 


A dd Mo aa pea aL 2); 
or to deselect icons (such as a “trash’ 


SetCtlVelue(GetCt Ve lueCtheSe lec tedContro] 2-1; 
• HiliteControl doesn't change anything; 


• SizeControl only moves the gravity center of the control; 
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° never use SctCtlMin and SetCtlMax; 
e the other routines (MoveControl, SetCTitle, HideControl, 

ShowControl) work the way you might expect. 

Example Listing 

I give hereafter the listing of the ‘MDEF’ and the 'CDEF' 
resources in LightSpeed Pascal as well as a minimum shell 
program as an example of how to use the custom controls. I 
apologize for the roughness of its interface: no standard menus, 
no "РА... shows at least the simplicity for the end program- 
mer. 

Future Extensions 

A feature found in the Finder and that I didn’t implement is 
the ability of editing the title of the icon. It would probably need 
to define two parts in the control. 

In some applications, pop-up menus change their title ac- 
cordingly to the current choice. It could be possible here at the 
condition that the menu handle of the control is left unchanged, 
even though the title or the icon handle are changed. 

At last, what would be “vachement classe” and truly up-to- 
date custom Mac programming is acolor-hierarchical-pop-up- 
icon-user-menu ! 

Please send me a copy once you ve written this marvel, or 
simply send me bug-reports and comments to: 

Jean de Combret 

Diadéme Ingénierie 

25, avenue de Constantine 

38100 GRENOBLE 

France 


Listing 1: Control manager example 


(oooeoeooooooooooeoooecococococoooooeeoeeeeeeocoeeee) 


( SPYING THE CONTROL MANAGER^S MESSAGES TO THE CDEF ) 


(FOCI GOO ) 


( Put this file in the project after MacPasLib and MacTraps. } 
( Don’t forget “Use resource file” in “Run options” of menu ) 
( This resource file may be empty, or may contain a copy of } 
( system file reources CDEF 0 and 1) 
Qooeocooooooooooocoooocooodooeooooooooooooooooee) 
PROGRAM Controls; 
CONST 
CDEFID = 1; (0 for button, 1 for scroll bar ) 
TYPE 
CDEFcodeHdl = ^CDEFcodePtr; 
CDEFcodePtr = ^CDEFcodeRecord; 
CDEFcodeRecord = RECORD 
jump : integer; 
address : ProcPtr; 
END; 
VAR 
boundsRect, TextRect : rect; 
muControl, whichControl : ControlHandle; 
theEvent : eventRecord; 
thePoint : point; 
whichPart : integer; 
theWindow, whichWindow : WindowPtr; 
myFakeCDEF : CDEFcodeHdl; 
myFakeCDEF id : integer; 
CDEFProcHandle : handle; 
LABEL 
1; 25 
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FUNCTION DoCDEF CvarCode : 
Handle; message : 
handle) : longint; 

INLINE i 
( CDEF relies on prepared default value of Ø as funct. 
result:) 

$42AF, $0010, (CLR.L 19CA7)) 


integer; theControl : Control- 
integer; param : longint; ProcHandle : 


( JSR to a procedure passed by handle as last argument ) 


$205F, (MOVE.L (А72%,А0) 
$2050, (MOVE.L (A0),A0) 
$4E90; (JSR (A02) 


FUNCTION ControlProc CvarCode : 
ControlHandle; message : 
BEGIN 
writelnC' 
ControlProc 
CDEFProcHandle); 
END; 


BEGIN 
( create a intermediate CDEF resource : } 
myFakeCDEF := 
CDEF codeHd1 (NewHandle(s izeof (CDEFcodeRecord))); 
IF MemError © NoErr THEN 
GOTO 2; 
myFakeCDEF**.jump := $4EF9; 
myFakeCDEF**. address := @ControlProc; 


REPEAT 
myFakeCDEFid := UniqueIDC'CDEF ^); 
( in order to have 16*myFakeCDEFid < maxint : ) 
UNTIL myFakeCDEFid < 1000; 


integer; theControl : 
integer; param : longint) : longint; 


message- ', message, ‘param= ', param); 
‘= DoCDEF(CvarCode, theControl, message, param, 


AddResourceChandle(myFakeCDEF), ‘CDEF’, myFakeCDEFid, '^); 
IF ResError © NoErr THEN 
GOTO 2; 


SetRect(TextRect, 250, 40, 500, 330); 
setTextRect(TextRect); 
ShowText; 
SetRect(boundsRect, 40, 40, 200, 200); 
theWindow := NewWindow(NIL, boundsrect, ‘my window’, true, 
0, pointer(- 12, false, 0); 
SetPort( theWindow); 
CDEFProcHandle := GetResource(‘CDEF’, CDEFID); 
IF ResError © NoErr THEN 
GOTO 1; 
HLock(CDEFProcHandle); 
IF MemError «» NoErr THEN 
60TO 1; 
SetRect(boundsRect, 10, 10, 90, 26); 


( now we begin to test the Control Manager’s routines : } 


writelnC'NewControl : ‘); 

myControl := NewControlCthePort, boundsRect, ‘my control’, 
true, 0, 0, 48, myFakeCDEFid * 16, 0); 
setCtlAction(myControl, pointer(-1)); 

writelnC'SetCTitle : ^); SetCTitleCmyControl, ‘new name’); 
writelnC'HideControl : ^); HideControl(mgContro1); 
writelnC'ShowControl : ^); ShowControl(mgContro1); 
writelnC'HiliteControl : “); HiliteControl(myControl, 1); 
writelnC'HiliteControl : ^); HiliteControlCmyControl, 255); 
writelnC'HiliteControl : ^); HiliteControl(myControl, 0); 


writelnC'SetCtlValue : ^); SetCtlValue(mgControl, 1); 
writelnC'SetCtlMax : '2; SetCtlMax(mgControl, 0); 
writelnC'SetCtlMax : “); SetCtlMax(ngControl, 1); 
writelnC'SetCtlMin : “); SetCtlMin(mgControl, 1); 
writelnC'SetCtlMin : '2; SetCtlMin(mgControl, 0); 
writelnC'SetCtlValue : ^); SetCtlValueCngControl, 0); 
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writelnC'MoveControl : 


^); MoveControl(muControl, 28, 20); 
writelnC'SizeControl : 


^); SizeControlCmyControl, 100, 30); 


( let’s have loop to test “ТгаскСопіго1* and "FindControl^: ) 
writelnC'The user should try actions on the control. 7); 
writelnC'End by clicking outside the control. ^); 
FlushEvents(EveryEvent, 0); InitCursor; 
REPEAT 
REPEAT 
UNTIL GetNextEventCMDownMask, theEvent); 
thePoint := theEvent where; 
whichPart := FindWindowCthePoint, whichWindow); 
SetPort(whichWindow); GlobalToLocal(thePoint); 
writelnC'FindControl : °); 
whichPart := 
FindControl(thePoint, whichWindow, whichControl); 
IF whichControl © NIL THEN 


BEGIN 
writelnC'TrackControl : °); 
whichPart := 
TrackControl(whichControl, thePoint, pointer (- 122; 
END; 


UNTIL whichControl = NIL; 


FlushEventsCMUpMask, 0); 
( let's е another loop to test "DragControl^ (and "FindCon- 
trol”) : 
writelnC'The user should try to drag the control.^); 
writelnC'End by clicking outside the control. 72; 
REPEAT 
REPEAT 
UNTIL GetNextEventCMDownMask, theEvent); 
thePoint := theEvent .where; 
whichPart := FindWindowCthePoint, whichWindow); 
SetPortCwhichWindow); GlobalToLocal(thePoint); 
writelnC'FindControl : “); 
whichPart := 
FindControlCthePoint, whichWindow, whichControl); 
IF whichControl © NIL THEN 
WITH whichWindow^ DO 
BEGIN 
writelnC'DragControl : “); 
DragControlCwhichControl, thePoint, PortRect, 
PortRect, noConstraint); 
END; 
UNTIL whichControl = NIL; 
writelnC'DisposControl : ‘); DisposeControl(muControl); 
writeln(‘end’); 


1: 

( let’s remove our fake CDEF : ) 
RmveResource(handle(muFakeCDEF)); 
IF ResError «» NoErr THEN 

GOTO 2; 
DisposHandleChandle(CmyFakeCDEF )); 


( error label : } 
2.4 
END. 


(YXXX1XXX1XXXX13XXX15XX1XXXXXXXXXXXXXXXXXXXXXXXXXXX) 


( BUILDING THE MDEF CODE RESOURCE 

(Cooooeeeeoocoecoec eee eee eec eee COCOCEEEXEEGEOEOEOEOEEEEX) 

( Put this file in the MPOP Project after DAPasLib. ) 

( Don't put MacTraps that would generate unusefull glue for 
the Memory Manager. ) 

( I prefer to declare DisposHandle as inline procedure : see 
below. ) 

( Don^t forget to "Use resource file? in "Run options” of menu 
“Project”. ) 

( This resource file must contain the MENU and ICN! resources) 
( that the PopTrap Project needs together with the compiled 
MDEF resource. ) 
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( “Build and save as.^ resource code of type MDEF and ID 128 
in file “MPOP code” ) 
(YXXXXX1XX1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) 


UNIT MPOP; 


INTERFACE 
( the name “Main? indicates to LightSpeed Pascal compiler 
where the entry point is } 


PROCEDURE Main (message : integer; theMenu : MenuHandle; VAR 


menuRect : rect; hitPt : point; VAR whichItem : integer); 
IMPLEMENTATION 
CONST 


mPopUpMsg = 3; 
( and not 4 as written in early versions of new MenuMgr } 


PROCEDURE CopyMask (srcBits, maskBits, dstBits : BitMap; 
srcRect, maskRect, dstRect : Rect); 
INLINE $4817; 


PROCEDURE DisposHandle (h : handle); 
( to avoid putting the whole Memory Manager glue in our code 
resource 

INLINE $205F, $4023, $31C0, $0220; 


(YX1XXXXX1XX1XXX111XXXXXXXXXXXX3XXXXXXXXXXX) 
( first some utilities for reading MENU resources : ) 


FUNCTION GetNextBute (VAR LongAddress : 


longint) : bute; 
INLINE 


$205F, ( MOVEA.L САТ)+,А0 ) 
$2250, ( MOVEA.L CAB), All) 

$5298, ( ADDQ.L "$1 (А0) } 
$204F, ( MOVEA.L A7,A9 ) 
$4218, ( CLR.B (AQ)+ ) 
$1091; ( MOVE.B (A12, CA02) 


FUNCTION GetNextInteger (VAR LongAddress : longint) : 
integer; 
INLINE 


$205F, ( MOVEA.L (A7)*5,A0 ) 
$2250, ( MOVEA.L САЙ),А1 ) 
$5490, ( ADDQ.L "$2 (AQ)  ) 
$204F, ( MOVEA.L АТ,А0 ) 
$1009, ( MOVE.B (A1)+, САО )+ ) 
$1091; ( MOVE.B CA1), CAO)  ) 
FUNCTION GetNextString (VAR LongAddress : longint) : 
StringHandle; 
( returns NIL if allocation failed ) 
INLINE 


$205F, ( MOVEA.L 
$2250, ( MOVEA.L 
$7000, ( MOVEQ 

$1011, ( MOVE.B 
$2200, ( MOVE.L 


(A7)*,A0 ;Аб: =@1 опдАддгеѕѕ ) 
(А ),А1 ;A1:=LongAddress ) 
8%00,00 ¿countChars:=0@0 ) 
(А12,00 ;countChars:-LongAddress^ ) 
00,01 ;5әуе countChars } 
$5200, ( А000.8 #$1,DØ ; length:=countChars+1 ) 
$0190, ( ADD.L DØ, CAD) 

;FuturLongAddress :=LongAddresstlength ) 
$4122, ( OSTRAP $А122 ;A0:-NewHandle(Dslength) ) 
$4480, ( TST.L 00 ;if MemError } 


$660C, ( BNE.S *4$000E ;O goto error ) 
$2E88, ( MOVE.L — A0, САТ) ¿GetChaine:=A0 ) 
$2050, ( MOVEA.L САЙ), A0 *StringPtr ) 
( loop ;repeat ) 
$1009, ( MOVE.B CA1)+, САЙ )+ 
;StringPtr* :=LongAddress* ) 
$51C9, $FFFC, ( DB D1, *-$0002 


;dec(length); until length«0 ) 


$6002, ( BRA.S х:%0004 ;goto bottom } 
( error ) 

$4297; ( CLR.L (AT) ;GetChaine:=NIL ) 
( bottom ) 
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FUNCTION SkipNextString (VAR LongAddress : longint) : byte; 
VAR length : byte; 
BEGIN 
length := GetNextByteCLongAddress); 
LongAddress := LongAddress + length; 
SkipNextString := length; 
END; 


PROCEDURE SkipBytes (VAR LongAddress : longint; 
byteCount : integer); 
BEGIN 


LongAddress := LongAddress + byteCount; 
END; 


(foooociooooooceooooooooocooooooococoooooooo 


PROCEDURE Main; 


FUNCTION GetItemCenter : point; 
( returns the ItemCenter in local coordinates, relative to 
menuRect ) 
( theMenu is already locked ) 
VAR 
LongAddress : longint; 
length : byte; 
i : integer; 
ItemCenter : point; 
BEGIN 
LongAddress := ord(theMenu*) + 14; 
length := SkipNextStr ing(LongAddress); 
i := Ø; 
REPEAT 
i := i+ 1; 
length := SkipNextString(LongAddress); 
IF length > Ø THEN 
BEGIN 
IF i = whichItem THEN 
BEGIN 
ItemCenter.v := GetNext Integer (LongAddress); 
ItemCenter.h := GetNextInteger(LongAddress); 
END 
ELSE 
BEGIN 
Sk ipBytesCLongAddress, 4); 
7 
END 
ELSE (АҒ length<=0 : ) 
SetPt(ItemCenter, 0, 0); 
UNTIL (length <= 0) OR Ci = whichltem); 
GetItemCenter := ItemCenter; 
END; 


шылы аз 


PROCEDURE DoDrawMessage; 


PROCEDURE PinString (theString : Str255; 
center : point); 
BEGIN 


WITH center DO 
Movelo(h - StringWidth(theString) DIV 2, v); 
DrawString(theString); 

END; 


PROCEDURE PlotIconDataCopu 
(thelcon : handle; dstSquare : rect); 
VAR 
srcSquare : rect; 
data : bitməp; 
muPort : GrafPtr; 
BEGIN 
IF (thelcon € NIL) THEN 
BEGIN 
SetRect(srcSquare, -16, -16, 16, 16); 
data.rowButes := 4; 
data.baseAddr := ptr(theIcon^); 
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data.bounds := srcSquare; 
GetPort(muPort); 
CopuBits(data, myPort*.portbits, srcSquare, 
dstSquare, srcCopy, NIL); 
END; 
END; 


VAR 
IconRect : rect; IconName : StringHandle; 
LongAddress : longint; NameLength : byte; 
ItemCenter, TextCenter : point; 
theIcon : handle; 
BEGIN 
LongAddress := ord(theMenu^) + 14; 
NameLength := SkipNextStr ingCLongAddress); 
REPEAT 
IconName := GetNextStringCLongAddress); 
NameLength := lengthCIconName**); 
IF NameLength > 0 THEN 
BEGIN 
theIcon := GetNamedResource(‘ICN#’, IconName^^); 
ItemCenter.v := GetNextInteger(LongAddress) + 
menuRect. top; 
ItemCenter.h := GetNextInteger(LongAddress) + 
menuRect. left; 
WITH ItemCenter DO 
BEGIN 
SetRectCIconRect, h - 16, v - 21, h + 16, v + 11); 
SetPt(TextCenter, h, v + 20); 
END; 
PlotIconDataCopyCtheIcon, IconRect); 
Tex tFont(geneva); 
TextSize(9); 
PinString(IconName**, TextCenter); 
TextFont(systemFont); 
TextSize( 12); 
END; 
DisposHandleChandleCIconName)); 
UNTIL NameLength <= 0; 
END; ( of DoDrawMessage ) 


(ххх ххх ххх жж жа) 


PROCEDURE DoChooseMessage; 


FUNCTION GetIconRect : rect; 
( returns the IconRect in global coordinates ) 
VAR 
ItemCenter : point; 
IconRect : rect; 
BEGIN 
ItemCenter := GetItemCenter; 
WITH ItemCenter DO 
BEGIN 
IF (h = 0) AND (v = 0) THEN 
SetRect(IconRect, 0, 0, 0, 0) 
ELSE 
SetRect(IconRect, h - 16, v - 21, h + 16, v + 11); 
END; 
WITH menuRect DO 
OffSetRectCIconRect, left, top); 
GetIconRect := IconRect; 
END; ( of GetIconRect } 


PROCEDURE PlotIconMaskXor 
(theIcon : handle; dstSquare : rect); 
VAR | 
srcSquare : rect; mask : bitmap; 
myPort : GrafPtr; 
BEGIN 
IF (thelcon © NIL) THEN 
BEGIN 
SetRect(srcSquare, -16, -16, 16, 16); 
mask.rowButes := 4; 
mask .baseAddr := ptr(ord4(thelcon") + 128); 
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mask.bounds := srcSquare; GetPort(muPort); END 
CopuBits(mask, myPort^.portbits, srcSquare, ELSE IF itemNumber € whichItem THEN 
dstSquare, srcXOr, NIL); ( hitPt is in itemRect ) 
END; BEGIN 
END; ( of PlotIconMaskXor ) IF whichItem © Ø THEN 
InvertIcon(whichItem, GetIconRect); 
FUNCTION GetIconName (whichItem : integer) : String- WITH ItemCenter DO 
Handle; ( theMenu is already locked ) SetRectCIconRect, h - 16, v- 21, h + 16, v + 11); 
VAR WITH MenuRect DO 
LongAddress : longint; length : byte; OffSetRectCIconRect, left, top); 
i: integer; IconName : StringHandle; InvertIconCitemNumber, IconRect); 
BEGIN whichItem := itemNumber; 
LongAddress := ord(theMenu^) + 14; END; 
length := SkipNextStr ingCLongAddress?; END; ( of DoChooseMessage ) 
i := 0; 
REPEAT (¥EREKKKE KER AE ERE AA ERA AA AAA AAA акк) 
і = i+ 1; PROCEDURE DoSizeMessage; 
IF i = whichItem THEN ( theMenu is alreadu locked ) 
BEGIN 
IconName := GetNextString(LongAddress); PROCEDURE RectAndPt (VAR theRect : rect; 
END thePoint : point); 
ELSE BEGIN 
BEGIN WITH theRect, thePoint DO 
length := SkipNextStr ing(LongAddress); (же suppose that 0=left<right and 0=top<bottom ) 
IF length > 0 THEN BEGIN 
SkipButes(LongAddress, 4) IF h > right THEN right := h; 
ELSE IF v > bottom THEN bottom := v; 
IconName := NIL; END; 
END; END; 
UNTIL Clength <= Ø) OR Ci = whichItem); 
GetIconName := IconName; VAR 
END; LongAddress : longint; length : byte; 
ItemCenter : point; Envelope : rect; 
PROCEDURE InvertIcon BEGIN 
(whichItem : integer; dstSquare : rect); LongAddress := ord(theMenu^) + 14; 
VAR length := SkipNextStringCLongAddress?; 
IconName : StringHandle; SetRect(Envelope, 0, 0, 0, 0); 
mulcon : handle; REPEAT 
BEGIN length := SkipNextString(LongAddress); 
IconName := GetIconName(whichItem); IF length > 0 THEN 
mulcon := GetNamedResource(‘ICN®’, IconName**); BEGIN 
PlotIconMaskXor(myIcon, dstSquare); ItemCenter.v := GetNextInteger(LongAddress); 
END; ItemCenter.h := GetNextInteger(LongAddress); 
RectAndPt(envelope, ItemCenter); 
VAR END 
itemNumber : integer; NameLength : byte; UNTIL (length <= 0); 
LongAddress : longint; ItemCenter : point, WITH theMenu^^, envelope DO 
ItemRect, OldIconRect, IconRect : rect; BEGIN 
BEGIN ( DoChooseMessage ) menuWidth := right + 25; 
LongAddress := ord(theMenu^) + 14; menuHeight := bottom + 25; 
NameLength := SkipNextStr ingCLongAddress); END; 
itemNumber := 0; END; ( of DoSizeMessage } 
REPEAT 
itemNumber ‘= itemNumber + 1; (Xxxiooocoeoooeoeeoeececeo eoe ee eee oeoe egeo) 
NameLength := SkipNextStr ing(LongAddress) ; PROCEDURE DoPopUpMessage; 
IF NameLength > @ THEN ( оп entry: whichItem(=popUpItem) , } 
BEGIN ( hitPt (= center of title icon) } 
ItemCenter.v := GetNextInteger(LongAddress); ( theMenu (Locked) } 
ItemCenter.h := GetNextIntegerCLongAddress); ( on exit : menuRect ) 
WITH ItemCenter DO ( ThePort is allready set to WindowManager Port ) 
SetRectCItemRect, h - 25, v - 25, h + 25, v + 25); VAR 
WITH menuRect DO ItemCenter, IconCenter : point; dh, dv : integer; 
OffSetRectCItemRect, left, top); WMPort : GrafPtr; mBarHeight : ^integer; 
END; BEGIN 
UNTIL (NameLength <= 0) OR mBarHeight := роіпіег(%ВАА); 
(PtInRectChitPt, ItemRect)); WITH theMenu^^, hitPt DO 
IF NameLength <= 0 THEN SetRect(menuRect, h, v, h + menuWidth, v + MenuHeight); 
( hitPt is not in any item ) IF whichItem » 2 THEN 
BEGIN BEGIN 
IF whichItem © Ø THEN ItemCenter := GetItemCenter; 

BEGIN WITH ItemCenter DO 
InvertIcon(whichItem, GetIconRect); SetPtCIconCenter, h, v - 5); 
whichItem := 0; WITH IconCenter DO 

END; IF NOT (Ch = 0) AND (v = 0)) THEN 
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OffSetRect(menuRect, -h, -v) 
ELSE 
whichItem := Ø; 
END; 


IF whichItem <= 0 THEN 
OffSetRect(menuRect, -25, +25); 
GetPortCWMPort); 
WITH WMPort* DO 
BEGIN 
IF menuRect.right + 8 > PortRect.right THEN 
dh := PortRect.right - menuRect.right - 8 
ELSE IF menuRect.left - 8 < PortRect. left THEN 
dh := PortRect.left - menuRect. left + 8 


ELSE dh := 0; 
IF menuRect.bottom + 8 >) PortRect.bottom 
THEN 
dv := PortRect.bottom - menuRect.bottom - 8 
ELSE IF 

menuRect.top - 8 < PortRect.top + mBarHeight^ 
THEN 


dv := PortRect.top + mBarHeight^ 
- menuRect.top + 8 
ELSE dv := 0; 
END; 
Of fSetRect(menuRect, dh, dv); 
END; ( of DoPopUpMessage ) 


(AAO x) 


BEGIN ( of Main } 
CASE message OF 
mSizeMsg : DoSizeMessage; 
mDrawMsg : DoDrawMessage; 
mChooseMsg : DoChooseMessage; 
mPopUpMsg : DoPopUpMessage; 


2 


END; 
END. 


(Y13133 1332333535 5 XX355XXXXXXXXXXXXXXXXXX34XXXXXXXX) 
{ BUILDING THE CDEF CODE RESOURCE 


(79 GCI k k } 


( Put this file in the CDEF Project after DAPasLib, MacTraps, 
ROM851ib and ROM85. ) 
( Don’t forget to “Use resource file” in “Run options” of menu 
“Project”. } 
( This resource file must contain the WIND ,CNTL, MENU, ICN®, 
ICON, MDEF ) 
( resources that the Shell Project needs together with the 
compiled CDEF resource. ) 
( "Build and save as." resource code of type CDEF and ID 128 
in file "CDEF code” ) 
(ХХХ ххх жж) 
UNIT CDEF; 
ІНТЕРҒАСЕ 

USES ROM85; 


FUNCTION Main (varCode : integer; 
theControl : ControlHandle; message : integer; 


param : longint) : longint; 
IMPLEMENTATION 
CONST | 
RestState = 0; SelectState = 1; OpenState = 2; 
SelectOpenState = 3; ThrownAwauState = 4; 
MenuReturnState = 5; 


movableBit = 1; doubleClickableBit = 2; 
trashBit = 3; menuBit = 4; 
varCodeBase = 200; 
( bit-offset of end of varCode in ControlRecord ) 
integerLength = 16; 
TYPE 


DataHandle = “DataPointer; 
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DataPointer = “DataRecord; 
DataRecord = RECORD 
theIcon : handle; 
theMenu : MenuHandle; 
END; 


FUNCTION PopUpMenuSelect (menu : MenuHandle; 
top, left, popUpItem : integer) : longint; 
INLINE 
$480B; 


PROCEDURE PlotDoubleIcon CtheIcon : handle; 
State : integer; dstSquare : rect); 
VAR 


srcSquare : rect; 
data, mask, destBitMap, scratchBitMap : bitmap; 
theGrafPort : GrafPtr; 
LightGraylcon, DarkGrayIcon : handle; 
BEGIN 
IF CtheIcon © NIL) THEN 
BEGIN 
SetRect(srcSquare, -16, -16, 16, 16); 


data.rowBytes 4; 
data.baseAddr ptrCtheIcon^); 
data.bounds := srcSquere; 


mask .rowBytes 4; 
mask .baseAddr ptrCord4CtheIcon^) + 128); 
mask .bounds :- srcSquare; 


GetPortCtheGrefPort); 
destBitMap := theGrafPort*.portbits; 
CASE state OF 
RestState : 
BEGIN 
CopyBits(mask, destBitMap, srcSquare, dstSquare, 
7 
CopuBits(data, destBitMap, 
NIL); 


srcBic, 


srcSquare, dstSquare, ѕгс0г, 
END; 
SelectState : 
BEGIN 
( old finder : ) 
CopyBits(mask, destBitMap, 
NIL); 
CopyBitsCdata, destBitMap, 
NIL); 
CopyBits(mask, destBitMap, 
NIL); 
{ new finder would be : } 
Co destBitMap, srcSquare, dstSquare, srcOr, 
nil); 
ee destBitMap, srcSquare, dstSquare, srcBic, 
nil); 


srcSquare, dstSquare, srcBic, 


srcSquare, dstSquare, srcOr, 


srcSquare, dstSquare, srcXOr, 


END; 
OpenState : 
BEGIN 
WITH scratchBitMapDO 
BEGIN 
LightGrayIcon := GetIcon( 128); 
BaseAddr := LightGrayIcon^; 
bounds := srcSquere; 
Rowbytes := 4; 
END; 


CopyBits(mask, destBitMap, srcSquare, 
dstSquare, srcBic, NIL); 

CopyMask(scratchBitMap, mask, destBitMap, 
srcSquare, srcSquere, dstSquare); 

SelectOpenState : 
BEGIN 
WITH scratchBitMap DO 
BEGIN 
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DarkGraulcon := GetIcon(129); 


BaseAddr := Daerk6rayIcon^; 
bounds := srcSquare; 
Rowbutes := 4; 

END; 


CopuBits(mask, destBitMap, srcSquare, 
dstSquare, srcBic, NIL); 
| CopyMask(scratchBitMap, mask, destBitMap, 
srcSquare, srcSquare, dstSquare); 


OTHERWISE 
END; 
END 
END; ( of PlotDoubleIcon ) 


( ЖЖЖЖЖЖЖЖЖЖХАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 


FUNCTION distance (startPt, endPt : point) : integer; 
BEGIN 


distance := abs(startPt.h - endPt.h) + abs(startPt.v - 
endPt.v); 
END; 
FUNCTION InsideIcon (myPoint : point; 
IconCenter : point; 
myIcon : handle) : boolean; 
VAR 


bitOffset : longint; 
scratchMap, dataMap, maskMap, sensitiveMap : bitmap; 
square : rect; 
x, y : integer; 
LABE 
1; 
BEGIN 
HLock(myIcon); 
SetRect(square, 0, 0, 32, 32); 
WITH scratchMap DO 
BEGIN 
bounds := square; 
BaseAddr := NewPtr( 128); 
IF MemError © NoErr THEN 
GOTO 1; 
RowBytes :- 4; 
END; 
WITH sensitiveMap DO 
BEGIN 
bounds := square; 
BaseAddr := NewPtr(128); 
IF MemError <> NoErr THEN 
GOTO 1; 
RowBytes :- 4; 


END; 
WITH dataMap DO 
BEGIN 
bounds := square; 
BaseAddr := mulcon ; 
RowButes := 4; 
END; 
WITH maskMap DO 
BEGIN 
bounds 
BaseAdd 


:= square; 
PtrCord4(myIcon^? + 128); 
4 


2 


CopuBits(maskMap, scratchMap, square, square, srcCopu, 
NIL); 
CopuBits(dataMap, scratchMap, square, square, 5гс0г, NIL); 
CalcMask(scratchMap.baseAddr, sensitiveMap.baseAddr, 4, 4, 
32, 2); 
x := myPoint.h - IconCenter.h + 16; 
y := myPoint.v - IconCenter.v + 16; 
IF NOT (Cx IN [0..31]) AND Cy ІМ (0..31])) THEN 
Insidelcon := false 
ELSE 
BEGIN 
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bitOffset := x + 32 х y; 
InsideIcon := BitTst(sensitiveMap.baseAddr, bitOff- 


END; 
HUnLock(myIcon); 
DisposPtr(scratchMap .baseAddr ); 
DisposPtr(sensitiveMap.baseAddr 2; 


set); 


IF MemError © NoErr THEN 
InsideIcon := false; 
END; 


FUNCTION DoubleClick CtheControl : ControlHandle; 
startPt : point; startTime : longint; VarCode : integer; 
bounds : rect; VAR IconCenter : point) : boolean; 
VAR 
mouse : point; t : longint; d : integer; 
theEvent : EventRecord; DoubleClicked : boolean; 


PROCEDURE DragSquare (startPt : point; 
VAR IconCenter : point); 
VAR 
oldFrame, frame, bounds : rect; 
delta, mouse : point; theGrafPort : GrafPtr; 
grayPattern : pattern; theTrash : ControlHandle; 


PROCEDURE HighLightTrash (mouse : point); 
VAR 
where : integer; IconCenter : point; 
OverFlownControl : ControlHandle; 
BEGIN 
where := FindControl(mouse, FrontWindow, 
FlownControl); 
HLockCGetResourceC'CDEF ^, 12825; 
FrameRect(oldFrame); 
IF theTrash € OverFlownContro] THEN 
( the control the mouse overflyes is no more “theTrash” ) 
BEGIN 
IF theTrash © NIL THEN 
( the mouse has ended overf lying a trash ) 
BEGIN 
SetCtlValueCtheTrash, GetCtlValueCtheTrash) - 1); 
HLock( theTrash** . Contr IDefProc?; 
END; 
IF KOverFlownContro! «€» NIL) THEN 
IF BitTstCpointerCOverFlownControl^2, 
varCodeBase - trashBit) AND 
CtheControl € OverFlownControl) 
THEN 
( the mouse begins overflying a trash ) 
BEGIN 
SetCtlValueCOverF lownControl, 
GetCtlValueCOverFlownControl) + 1); 
HLock(OverFlownControl* *.Contr]1DefProc); 
theTrash := OverFlownControl; 
END 
ELSE 
( the mouse overflies something else than a trash ) 
theTrash := NIL 
ELSE 
( the mouse doesn’t overfly anything ) 
theTrash := NIL; 
END; 
END; 


BEGIN ( DragSquare ) 
theTrash := NIL; 
Stuf fHexC@grayPattern, ‘SSAASSAASSAASSAA ' ); 
GetPor t( theGraf Port); 
bounds := theGrafPort* .PortRect; 
InSetRect(bounds, 16, 16); 
delta := IconCenter; 
SubPt(startPt, delta); 
PenMode(CPatXor); 


Over- 
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WITH IconCenter DO 
SetRect(oldFrame, h - 16, v - 
PenPat(grauPattern); 
FrameRectColdFrame); 
( instead of the surrounding squere ) 
( we could also drag the icon’s data or mask frame ) 
REPEAT 
GetMouse(mouse); IconCenter := mouse; 
AddPtCdelta, IconCenter); 
WITH IconCenter, bounds DO 
BEGIN 
IF h < left THEN h := left; 
IF h> right - 1 THEN h := right - 1; 
IF v < top THEN v := top; 
IF v > bottom - 1 THEN v := bottom - 1; 
END; 
WITH IconCenter DO 
SetRect(frame, h - 16, v - 16, h + 16, v + 16); 
IF NOT EqualRectColdFrame, frame) THEN 
BEGIN 


16, h + 16, v + 165; 


HighLightTrash(mouse); 
FrameRect(frame); oldFrame := frame; 
END; 
UNTIL NOT WaitMouseUp; 
FrameRect(frame); PenNormal; 


4 


BEGIN ( DoubleClick } 
DoubleClicked := false; 
BEGIN 


( if doubleClickable or movable : ) 
IF (BitTstCévarCode, 
integerLength - doubleClickableBit)) OR 
(BitTstCevarCode, integerLength - movableBit)) THEN 
REPEAT 
GetMouse (mouse ); 
d := distance(startPt, mouse); 
UNTIL (NOT WaitMouseUp OR (d > 3)); 
IF (d > 3) AND BitTst(@varCode, integerLength - 
movableBit) THEN 
DragSquare(startPt, IconCenter) 
ELSE IF BitTstCévarCode, 
integerLength - doubleClickableBit) THEN 
REPEAT 
Ge tMouse(mouse); 
d := distance(startPt, mouse); 
t := TickCount - startTime; 
IF GetNextEventCMDownMask, theEvent) THEN 
DoubleClicked := true; 


UNTIL DoubleClicked OR (d > 3) OR (t > GetDblTime); 


DoubleClick := DoubleClicked; 
END; 
END; 


( ЖЖЖЖЖЖЖАЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖХЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 


FUNCTION Main; 
VAR 
( color under the title : ) 
whitePattern : pattern; 


PROCEDURE DoDrawCnt1; 
VAR 
IconCenter, TextCenter : point; 
State, theLength, theHalfLength : integer; 
TextFrame, IconFrame : rect; 
myDataHandle : DataHandle; 
BEGIN 
State := GetCtlValue(theControl); 


( MenuReturnState is drawn like RestState, ThrownAwayState is 


not re-drawn : } 
IF State = MenuReturnState THEN 
State := RestState; 
IF ((State IN ([RestState. .SelectOpenState]) AND 
CtheControl**.ContriVis € 922) THEN 
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BEGIN 
HLockChandleCtheContro!2); 
WITH theControl^^ DO 

BEGIN 


TextFont(geneva); TextFaceCL 12; 
TextModeCSrcOr); TextSize(9); 
theLength := StringWidthCcontrlTitle); 
IF theLength < 32 THEN 

theHalfLength :- 16 
ELSE 


theHalfLength := theLength DIV 2; 
WITH ContrlRect DO 
SetPtCIconCenter, (right + left) DIV 2, 
(bottom - 12 + top) DIV 2); 
( recalculate the rect surrounding the whole control : ) 
WITH IconCenter, ContrlRect DO 
BEGIN 
left := h - theHalfLength; top := v - 16; 
right := h + theHalfLength; bottom := v + 16 + 12; 
ND; 
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WITH IconCenter, IconFrame DO 
BEGI 
left := h - 16; top := v - 16; 
right := h + 16; bottom := v + 16; 
END; 


( draw the icon-control’s title : ) 
WITH IconCenter DO 
setPt(TextCenter, h, v + 26); 
WITH TextCenter DO 
SetRect(TextFrame, h - theLength DIV 2, 
v - 10, h + theLength DIV 2, v + 2); 
Stuf fHexC@whitePattern, “0000000000000000:); 
FillRect(TextFrame, whitePattern); 
WITH TextCenter DO 
MoveToCh - theLength DIV 2, v); 
DrawStringCcontrlTitle); 
( draw the icon : ) 
myDataHandle := DataHandleCContriData); 
HLockCmyDataHandle** . theIcon); 
PlotDoubleIcon 
(nyDataHaendle^^.theIcon, State, IconFrame); 
HUnLockCmgDataHandle** . theIcon); 
END; 
HUnLock ChandleCtheControl)); 
END; 
Main := 0; 
END; 


PROCEDURE DoTestCnt1; 
VAR 
IconCenter, mouse : point; 
myDataHandle : DataHandle; 
BEGIN 
HLockChandleCtheContro12)2; 
WITH theControl^^ DO 
BEGIN 
SetPt(mouse, LoWord(param), HiWord(param)); 
IF PtInRect(mouse, ContriRect) THEN 
BEGIN 
WITH ContriRect DO 
SetPtCIconCenter, (right + left) DIV 2, 
Cbottom - 12 + top) DIV 2); 
myDataHendle := DataHandle(Contr Data); 
Main := ord4CInsideIcon(mouse, IconCenter, 
myDataHandle**. theIcon)); 
D 


main := 0; 


END; 
HUnLockChandle( theControl)); 
END; 


PROCEDURE DoCalcCRgns; 
CONST 


Lo3Bytes = $OOFFFFFF; 
VAR 
IconFrame, TextFrame : rect; theTitle : Str255; 
theLength, theHalfLength, halfWay : integer; 
BEGIN 
GetCTitleCtheControl, theTitle); 
theLength := StringWidth(theTitle); 
theHalfLength := theLength DIV 2; 
param := BitAnd(param, Lo3Bytes); 
IconFrame := theControl**.Contr Rect; 
WITH IconFrame DO 
BEGIN 
bottom := bottom - 12; halfWay := Cright + left) DIV 2; 
left := halfWay - 16; right := halfWay + 16; 
SetRect(TextFrame, halfWay - theHalfLength, 
bottom, halfWay + theHalfLength, bottom + 12); 
END; 
OpenRgn; 
FremeRectCIconFrame); FrameRect(TextFrame); 
CloseRgn(RgnHandle(Cparam)); 
Main := 0; 
END; 


PROCEDURE DeselectExcept 
CtheControl : ControlHandle); 
VAR 


myWindowPeek : WindowPeek; 
aControl : ControlHandle; 
BEGIN 
myWindowPeek := 
WindowPeek( theControl**.Contr 10wner ); 
aControl := myWindowPeek^ .ControlL ist; 
WHILE aControl <> NIL DO 


IF (aControl € theControl) THEN 
BEGIN 
IF (GetCtlValue(aControl) = 1) THEN 
BEGIN 
SetCtlValueCaControl, 0); 
HLockCaControl**.Contr1DefProc); 
END 
ELSE IF 
(GetCtlValueCaContro1) = 3) THEN 
BEGIN 
SetCtlValueCaControl, 2); 
HLockCaControl** .Contr IDef Proc); 
END 
END; 
aContro] := aControl**.nextControl; 
END; 
END; 
PROCEDURE DoAutoTrack; 
VAR 
SavedClip, UpDateRegion : RgnHandle; 
PopUpMenuHdl : MenuHandle; 
(MDEFPtr : Ptr;( for debugging only ) 
theTitle : Str255; 
choosenItem, dummy : longint; 
halfWay, theHalfLength, where : integer; 
oldCenter, IconCenter, mouse, MenuTitleCenter : 
theGrafPort : GrafPtr; 
theTrash : ControlHandle; 
myDataHandle : DataHandle; 
isAMenu, isDoubleClickable, isMovable : boolean; 
BEGIN 
isAMenu := BitTst(@varCode, integerLength - MenuBit); 
isDoubleClickable := BitTst(@varCode, integerLength - 
DoubleClickableBit); 


point; 


isMovable :- BitTst(@varCode, integerLength - MovableBit) 


IF isAMenu OR isDoubleClickable OR isMovable THEN 
BEGIN 
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IF GetCtlValueCtheControl) = OpenState THEN 
SetCtlValueCtheControl, SelectOpenState) 

ELSE IF GetCtlValueCtheControl) = RestState 
THEN SetCtlValueCtheControl, SelectState); 

қыны а 

DeselectExcept(theControl); 

GetMouse(mouse); 

WITH theControl^^.ContrlRect DO 
SetPt(IconCenter, (right + left) DIV 2, 

(bottom - 12 + top) DIV 2); 
oldCenter := IconCenter; GetPort(theGrafPort); 


( 19 : DOUBLE-CLICK ) 
IF DoubleClickCtheControl, mouse, TickCount, varCode, 
theGrafPort^.PortRect, IconCenter) THEN 
BEGIN 
SetCtlValueCtheControl, SelectOpenState); 
HLock( theContro1**.Contr1DefProc); 
END 


( 29 : NO DRAGGING } 
ELSE IF EqualPtColdCenter, IconCenter) THEN 
BEGIN 


( 2.1 : POPUPMENU ) 
IF isAMenu THEN 
BEGIN 
myDataHandle := DataHandleCtheControl^^.Contr Data); 
PopUpMenuHdl := myDataHandle**. theMenu; 


WITH theControl^^.ContrlRect, MenuTitleCenter DO 
BEGI 

h := Cleft + right) DIV 2; 
(top * bottom) DIV 2; 


У 


END; 

LocalToGlobal(MenuTitleCenter ); 

WITH MenuTitleCenter DO 
choosenItem := PopUpMenuSelect(PopUpMenuHdl, h, v, 9); 
( re-draw the control] as in RestState : } 

SetCtlValueCtheControl, MenuReturnState); 

HLock( theControl** .ContrDefProc); 

SetCRefConCtheControl, choosen! tem); 

END 


( 2.2 : SIMPLE SELECTION OF A DOUBLE-CLICKABLE CONTROL ) 
( the Control is already highlighted in the "SelectState^ ) 
END 


( 39 : DRAGGING ) 
ELSE 
BEGIN 
GetMouse(mouse); 
where := FindControl(mouse, FrontWindow, theTrash); 
HLockCGetResourceC'CDEF ^, 12872; 
IF CtheTrash € NIL) THEN 


(3.1: THROWING THE CONTROL AWAY IN A TRASH ) 
IF BitTstCpointer(theTrash*), 
varCodeBase - trashBit) 
AND СіһеТгавһ € theControl) 
THEN 
BEGIN 
( return *theTrash^ in CRefCon ) 
( without re-drawing it ) 
SetCRefConCtheControl, ordCtheTrash)2; 
SetCtlValueCtheControl, ThrownAwayState); 
HLock( theControl** .Contr1DefProc); 
END; 
( 3.2 : MOVING } 
IF (GetCtlValueCtheControl) © 
ThrownAwayState) THEN 
BEGIN 
WITH theControl**.ContriRect 00 
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theHalfLength := (right - left) DIV 2; 
( move the control without showing it : ) 
HideControlCtheContro12); 
HLockCtheContro1^*^ . Сопіг10еғРгос); 
WITH IconCenter DO 
MoveControl(theControl, 
h - theHalfLength, v - 16); 
HLock( theControl**.Contr1DefProc); 
theControl^^.ContrlValue := RestState; 


{ the UpDate mechanism will do the re-drawing in such a way it 
lets the previously hidden controls appear : } 


SavedClip := NewRgn; 
GetClip(SavedClip); 
SetEmptyRgn( theGrafPort*.ClipRgn); 
showControl(theControl); 
HLock( theControl**.Contr1DefProc); 
SetClipCSavedClip); 
( re-use an initialised region for another purpose : } 
UpDateRegion := SavedClip; 
( send the CalCRgns message to calculate UpDateRegion : } 
dummy := Маіп(0, theControl, 
calcCRgns, ord4(UpDateRegion)); 
EraseRgn(UpDateRegion); 
InValRgnCUpDateRegion); 
DisposeRgn(UpDateRegion); 


END; 
Main := 0; 
END; 
PROCEDURE DoInitCnt!; 
VAR 


myDataHandle : DataHandle; 
theTitle : Str255; 
BEGIN 
GetCTitleCtheControl, theTitle); 
myDataHandle := 
DataHandleCNewHandle(sizeof (DataRecord))); 
HLockChandleCmyDataHandle)); 
WITH myDataHandle^^ DO 
BEGIN 
theIcon := GetNamedResource(‘ICN®’, theTitle); 
( Initialisation should have called “GetMenu” : ) 
theMenu := MenuHandle(GetNamedResource( ‘MENU’, 
theTitle)); 
END; 
HUnLock Chandle(myDataHandle2); 
WITH theControl^^ DO 
BEGIN 
ContrlAction := pointer(-1); 
ContrlData := handleC(myDataHandle?; 
END; 
END; 


PROCEDURE DoDispCnt 1; 

BEGIN 
DisposHandleCtheContro1^^ .Contr Data); 
END; 


BEGIN ( Main procedure ) 
CASE message OF 
drawCnt! : DoDrawCnt1; 


testCntl : DolTestCntl; 
calcCRgns : DoCalcCRgns; 
initCnt] : DoInitCntl; 
dispCnt] : DoDispCntl; 
dragCnt! : ( for a smoother interface ) 
BEGIN 
DoAutoTrack; 
Main := 1; ( to tell the Control Manager not to 


use the standard method ) 
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autoTrack : DoAutoTrack; 
OTHERWISE ( dragCnt], posCnt! , thumbCnt] ) 
main := 0; 


Qooooooooooocooboocoooooopooeocooocoooocooponeooopboer) 


( SEE HOW SIMPLE IT IS FOR THE END-PROGRAMMER ) 
( TO CREATE AND USE FINDER-LIKE ICONS! } 
552252 222 222222222 2222222 222222222 2222222 
( Put this file in the Shell Project after DAPasLib, MacTraps, 
ROM851ib and ROM85, put also CDEF text if uou plan to improve 
and debug it. Don’t forget to “Use resource file” “CDEF Code” 
in “Run options” of menu “Project”. This resource file must 
contain the WIND ,CNTL, MENU, ICN®, ICON, MDEF and CDEF 
resource. ) 
(Жжжж) 
PROGRAM shell; 
USES ROM85; 
( , CDEFIcones; ( only for debugging purposes ) 
CONST 
RestState = 0; SelectState = 1; OpenState = 2; 
SelectOpenState = 3; ThrownAwayState = 4; 
MenuReturnState = 5; 
TYPE 
CDEFcodeHdl = ^CDEFcodePtr; 
CDEFcodePtr = ^CDEFcodeRecord; 
CDEFcodeRecord = RECORD 
jump : integer; 
address : ProcPtr; 
END; 
VAR 
whichWindow, myWindow : WindowPtr; 
whichControl, theTrash : ControlHandle; 
myCDEF : CDEFcodeHdl; theEvent : EventRecord; 
theControl : ControlHandle; mouse : point; 
FakeRect : rect; done : boolean; i : integer; 


PROCEDURE ProcessMenu (where : 
VAR 
MenuNb, ItemNb : integer; dummy : longint; 
i : integer; 


longint); 


BEGIN 
MenuNb := HiWord(where); 
ItemNb := LoWord(where); 


CASE MenuNb OF 
1 . 


FOR i := 1 TO ItemNb DO 
BEGIN 
SysBeep(5); 
DelayC 12, dummy); 
END; 
OTHERWISE 


END; 
END; 


PROCEDURE ProcessEvent; 
VAR 
myWindowPeek : WindowPeek; 
dummy : integer; 
BEGIN 
CASE theEvent.what OF 
UpDateEvt : 
BEGIN 
whichWindow := WindowPtr(theEvent message); 
beginUpDateCwhichWindow); 
IF whichWindow = myWindow THEN 
BEGIN 
EraseRgn(myW indow* .VisRgn); 
UpdtControlCmyWindow, myWindow*.VisRgn); 
END; 
endUpDateCwhichWindow); 
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END; 
MouseDown : 
BEGIN 
CASE FindWindowCtheEvent where, whichWindow) ОҒ 
inContent : 
BEGIN 
mouse :- theEvent where; 
GlobalToLocal(Cmouse); 
IF FindControl(mouse, whichWindow,whichControl) © 


BEGIN 
( choose DragControl or TrackControl as you prefer: ) 
( dummy :=TrackControl( theControl,mouse, pointer(-1)) ) 
SetRect(FakeRect, 0, 0, 0, 0); 
DragControlCwhichControl, mouse, FakeRect, Fak- 
eRect, noConstraint); 
IF GetCtiValueCwhichControl) = ThrownAwayState 
THEN 


BEGIN 

theTrash := ControlHandle(GetCRefConCwhichControl)); 
SetCtlValueCtheTrash, GetCtlValueCtheTrash) - 1); 
DisposeControlCwhichControl); 
END 

ELSE IF GetCtlValueCwhichControl) = MenuReturnState 


BEGIN 
ProcessMenu(GetCRefCon(whichControl)); 
( the Control has already been re-drawn in RestState, ) 


0 THEN 


THEN 


IF TrackGoAway(whichWindow, theEvent.where) 
THEN done := true; 
inDrag : 
DragWindow(whichWindow, theEvent.where, 
ScreenBi ts .bounds); 
OTHERWISE 
END; 
END; 
OTHERWISE 


END; 
END; 


BEGIN 
( create a intermediate CDEF resource : ) 

(myCDEF := CDEFcodeHdl(NewHandle(sizeof (CDEFcodeRecord))); 
( for debugging only ) 
(myCDEF^^ . jump := $4EF9; 


( for debugging only ) 
(nyCDEF^^ address := @main; 


( for debugging only ) 


ашыш ‘CDEF’, 128, “9; ( for debugging 
only 


myWindow := GetNewWindow( 128, NIL, pointer(-1)); 

Se tPor tCmyWindow); 

(BackPat(gray); { or whatever background pattern you wish ) 
InsertMenu(GetMenu( 128), -1); 


( so we don’t need to re-redraw it again.) FOR i := 128 TO 133 DO 
whichControl^^.ContrlValue := 0; theControl := GetNewControlCi, muWindow); 
END done := false; 
ELSE IF GetCtlValue(whichControl) = SelectOpenState SetCursor(arrow); 
THEN FlushEvents(EveruEvent, 0); 
BEGIN ShowWindow(muWindow); 
dummu := NoteAlert(128, NIL); REPEAT 
SetCtlValue(whichControl, RestState); IF GetNextEvent(EveruEvent, theEvent) THEN 
END ProcessEvent; 
ELSE UNTIL done; 
; DisposeWindow(muWindow); 
END; (RmveResource(handle(muCDEF)); ( for debugging only ) " 
END; (DisposHandleChandleCmyCDEF2); ( for debugging only ) Sol 
inGoAway : END. PEREA 
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Security Patrol for Viruses 


Politics of Virus Protection 

"SecurityPatrol" is a program I wrote to detect and option- 
ally remove the “nVIR” and “Scores” viruses (all Macintosh vi- 
ruses known at the time I wrote it), plus several other conditions 
I would find suspicious and would want to be warned about. This 
is version 1.1. It's been tested against live strains of nVIR and 
Scores. It contains a code database of "fingerprints" to identify 
known viruses and detect alterations of a system's “good” 
(trusted) resources by future viruses. [The source code disk for 
this month contains the complete library of system resource 
fingerprints for Security Patrol. In the interest of space, only a 
few example fingerprints are printed in the magazine. -Ed] 

It wasn'tcoded so much to be "user-friendly"; my main goal 
was to make it "security-stubborn": It's deliberately not easy to 
alter its code database of resources. You have to code them in 
manually and recompile. To putitanother way, the easier it is for 
a user to alter the database, the easier it is for a virus to alter the 
database and masquerade as something innocuous. 

On the other hand, there are advantages to the fact that it's 
being published in source code format. It allows you to re-code 
itto deal with future viruses and/or to make it deliberately incon- 
sistent with the published version. (A predictable defense is gen- 
erally a weakness to attack.) Another significant advantage is 
that it inherently discloses its behavior. Sunlight is a strong 
disinfectant. 

[While Apple Computer cannot and does not endorse any- 
thing in this article, it's publication in MacTutor was of sufficient 
concern that Scott Boyd, a contributing editor of MacTutor and 
a member of Apple's internal virus committee, asked and was 
given permission to review the article prior to publication. He 
indicated Apple's concern that an article of this sort that points 
out the system weaknesses can also give more ammunition to fuel 

future virsus makers. However, since three books have recently 
been published on how to create a computer virus, we feel the cat 
is out of the bag anyway so the protection this technology will 
allow developers is more vital than ever. Accordingly, we are 
publishing the article essentially unchanged from the author's 
version, except for a couple of places where Steven reveals 
"chinks in the armor" of Apple's system software. Scott did allow 
that many of Steven's techniques are being used in internal 
security programs at Apple so we feel this approach has merit. 
We invite comment on the problem that Scott and others at Apple 
must wrestle with: namely how much information should the 
public be given on the internal workings of Apple's system 
software and it's potential vulnerability to viral attack.-Ed] 
User Interface 

The program sends feedback to the screen and to areport file, 

but first the user has to select the report filename with a SFPut- 
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File (Save As...) dialog. If AppleTalk is active, pressing Cancel 
will cause it to Quit; if it's not active, pressing Cancel will cause 
it to stream the text toa direct-connect Image Writer on the printer 
port. (There’s a bug in TML II that causes WriteLn output to the 
ImageWriter not to work, but it'll be fixed soon. Inthe meantime, 
the user can send the report to a file or press Cancel to avoid 
creating areport file.) After selecting the report file, the user is 
presented with the Main Dialog. 


Main Dialog’s “Scope of Work” Buttons 

The user may want to patrol only a few files, or all files ina 
folder, or all files on several disks bought in a store. Maybe the 
user doesn’t have any particular files in mind, but wants to see 
whether or not any file on a partitioned hard disk is infected. The 
program cannot know in advance the scope of work to be done, 
so it asks the user in its Main Dialog. 

Directories: The program puts up an SFGetFile (Open...) 
dialog to allow the user to select a file. The program patrols all 
files under the directory that contains the selected file. Then, 
under HFS, it recursively patrols all subdirectories. Then it 
returns to the SFGetFile dialog. This process repeats until the 
user presses the Cancel button. 

Directory: Same as Directories, except that it doesn’t patrol 
subdirectories. 

Everything: The program loops thru all currently mounted 
volumes and patrols Directories (plural) on each one starting 
from the root directory. 

Files: The program puts up an SFGetFile dialog to allow the 
user to select a file, patrols only that file and returns to the 
SFGetFile dialog. This process repeats until the user presses the 
Cancel button. 

Quit: The program prints file and resource totals across all 
patrols before returning to the Finder. 


User Interface: Options 

The Main Dialog also has options the user (usually to get the 
user’s attention) and for the programmer (usually to help ease the 
non-trivial programming burden). Both kinds are controlled by 
check boxes. 

Await Keypress: When errors are reported, the program 
pauses until the user presses a key. 

Beep: The program beeps at you when suspicious condi- 
tions occur. Complaints get 1 beep, errors get 2 beeps, viral 
infections get 3 beeps and aborts get 4 beeps. (Most aborts are 
caused by programming errors, but they could also signify that 
the program is infected.) 

Fingerprint: The program lists the fingerprints of all execut- 
able resources it knows about, except CODEs. 
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Eingerprint CODEs: The program lists the fingerprints of 
CODE resources too, which generates a lot of output. 

Long Listing: The program lists all filenames to its report 
file, not just those that encountered errors. 

Remove Viruses: This is a last resort option for users to 
recover applications whose backups and masters are lost or 
unreadable. There are 3 major reasons why you might want to 
direct users not to use it: concern as to your legal liability if it 
doesn’t remove the virus properly (or damages uninfected appli- 
cations), a desire to encourage the safer method (restoring from 
backups) so as to limit future headaches, and the possibility of 
using the infected disk as evidence in acriminal or civil prosecu- 
tion (hard to do if you removed the virus as soon as you saw it). 

Trace: The program traces its flow. You may want to turn 
on Await Keypress to step thru it slowly. 

Program Design 

SecurityPatrol was dually developed under MDS-compat- 
ible TML Pascal I, version 2.5 (“TML 2.5”) апа MPW-com- 
patible TML Pascal II, version 1.0.2 (‘TML П”). Both ver- 
sions areon the source code disk, with TML 2.5 filenamesending 
in “.Pas” and TMLII filenames ending in “р”. The TML II files 
are the ones that appear in this article. 

Major differences: The TML 2.5 version is roughly 50K and 
3% faster, can output to a direct-connect ImageWriter on the 
printer port and types the report file as an MDS Edit document. 
The TML II version is roughly 60K, is much easier to develop in, 
has a larger text I/O window on larger monitors and types the 
report file as an MPW document. 

The program is broken up into 4 major modules: a main 
program called SecurityPatrol and 3 UNITs called Globals, 
MainDlog and Patrol. The TML 2.5 versions of these 4 are 
99% source code compatible; they differ only in the USES 
statement. In addition, the Globals UNIT of both versions 
include the “Fingerprint.ipas” file by means of the (SI) directive; 
that is, because it's 100% source code compatible, it's shared. 
The CodeSizeLimits UNIT is incompatible; there are different 
versions for TML 2.5 and TML II. Finally, there are BitProcs and 
PasLibIntf, which are used only in the TML 2.5 version to 
maintain source code compatibility with TML II. 

The files were named such that, under TML 2.5, dependency 
relationships are properly observed if you simply compile them 
inalphabetical order. Under TML II, youcanletthe TML Project 
Manager and MPW Make facility handle that for you. (I edit the 
SecurityPatrol.Proj file to recompile Globals.p if 
Fingerprint.ipas has changed, and to give the Fingerprint and 
Globals CODE resources the preload and locked attributes.) 

Within each module, the procedures are arranged alphabeti- 
cally for easy lookup. Since they aren't necessarily called in 
alphabetical order, some routines have to be declared FOR- 
WARD. 

As far as conversion to other Pascals is concerned, the 
following may help: The OUTPUT in the PROGRAM header is 
aTML  2.5conventionto tell the compiler that the program will 
use WriteLn, etc. TML also defines a Text file variable called 
OUTPUT that's implicitly used by all screen output WriteLn’s, 
etc, and PasLibIntf procedures. INC and DEC are built-in 
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functions to increment and decrement a variable by one. (Both 
are much faster than an assignment such as x :- x + 1 because they 
generate the ADDQ and SUBQ instructions.) That's all I can 
think of for now. 

Program Flow 

The MainDlog UNIT generates and maintains the Main 
Dialog display, keyboard equivalents and option check boxes 
internally. It returns to the main program when a Scope of Work 
button is pushed. 

The SecurityPatrol main program manages program initiali- 
zation, termination, text I/O and high-level interface between 
MainDlog and Patrol: Depending on the Scope of Work button 
pushed, it passes off to the proper routine of Patrol. 

The Patrol UNIT contains service routines to scan volumes 
and/or directories. (It's been programmed to work under both 
MFS and HFS, but it hasn't been tested under the 64K ROMs.) 
Its heart and soul is the recursive procedure PatrolDir, which, at 
the appropriate times, calls 5 routines in Globals: DirectoryBe- 
gins, DirectoryEnds, PatrolBegins, PatrolEnds and ProcessFile. 
Another routine in Patrol, called PatrolFiles (which patrols files 
manually, a file at a time), also calls those same routines in 
Globals. 

Globals is the largest UNIT and contains all the basic service 
routines. The first 4 routines just mentioned are currently given 
only trivial feedback duties at present. The 5th one (ProcessFile) 
is where all the action starts. If the file being processed contains 
CODE resources, ProcessFile calls ProcessCodes, which calls 
LookForKnownViruses and then looks for anomalies in the 
CODE Ojump table. Then, for every executable resource type 
it knows about, ProcessFile calls ProcessRsrcs with the address 
of a routine to process that resource type. LookFor- 
KnownViruses and ProcessRsrcs call routines in Fingerprint to 
do resource identification. If the Fingerprint routines say that a 
resource is infected, LookForKnownViruses calls a "Disin- 
fected” routine that knows how to restore the CODE 0 jump table 
before removing the infected resource(s); ProcessRsrcs calls 
RemovedRsrc directly to remove it. 

Fingerprint is where the “code database” of good (trusted) 
and bad resource identification resides. A resource’s fingerprint 
is a set of any tests you desire. In this article, 3 tests are used as 
the fingerprint; on the MacTutor source code disk(s), 7 tests. As 
new viruses are created, Fingerprint is where you would insert 
new code to detect them. 

Commentary on “CodeSizeLimits.p” 

CodeSizeLimits is used by PreprocessSelf in the main 
program, below. The idea behind it is to prevent a virus from 
creating a new CODE resource or imbedding itself in one of the 
existing CODE resources. 

Since TML II uses the standard MPW Link tool, which 
creates 9 CODE resources, the gSizeLimit array is 0..8 and 
gMaxCodeis8. The size limits for CODES 1 thru3 contain a little 
room for expansion, but not enough for even the tiny nVIR virus 
to fitinto. When you have the program the way you want it, you 
should set these values to exactly the same size as the CODE 
resources, so there won't be any room for a virus to sneak into. 
I have never seen CODEs 4 thru 8 be any size other than exactly 
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those shown, so I feel comfortable giving them no room for 
expansion. Unless you add, delete or move subroutines, gJTSize 
will always equal 1240, which represents 155 entries in the jump 
table. Under TML II, the main program’s main procedure 
cannot be referenced as if it were an external subroutine, because 
MPW Link doesn’t give us a symbolic name for it that we can 
reference. Tom Leonard suggested defining a subroutine just 
prior to the main program’s main procedure and adding a value 
to skip over its contents. The value turned out to be $1A. 
Commentary on “Fingerprint.ipas” 

FgPr: Fingerprinting begins with a call to InitFgPr and then 
proceeds by (possibly multiple) calls to FgPr. This allows a data 
fork to be fingerprinted even when it's larger than the I/O buffer. 
Calling TML’s built-in INC procedure twice is faster than the 
generic Pascal “sWordPtr := sWordPtr + 2;”, but not quite as fast 
as the new, equivalent TML II syntax: 
“INC(LONGINT(sWordPtr),2);”. 

As mentioned above, aresource’s fingerprintis a set of tests, 
any tests you desire. (The only significant restriction is that the 
test value isa LONGINT.) To fit within MacTutor column width 
restrictions, the version printed in this article uses only size, 
checksum, and checkxor. The version on the source code disk(s) 
uses those 3, plus the number of odd, negative, and positive 
words, and an alternating checksum/checkdiff. You shouldn't 
use only the 3 tests in this article, because it's possible to reverse- 
engineer an evil resource to have the same size, checksum and 
checkxor as a good one. The 7 tests used on the source code 
disk(s) make it a virtual certainty that, if two resources have the 
same fingerprint, they are bit-for-bit identical. 

If you want to invest your energies into modifying this 
program, it wouldn't be very fruitful to devise exotic new 
fingerprint tests. If you did manage to implement CRC-16, for 
example, and someone discovered a new virus, how would you 
find out what its CRC-16 value is?? If no one else has your test, 
you would need an actual copy of the virus to find out! (Scary!) 
It's better that there should be just a few common tests, not too 
computationally intense, the union of which approaches cer- 
tainty. It would be more fruitful if people devoted their efforts to 
searching more hiding places. In terms of the "security patrol" 
analogy, what we need are more guards on patrol, searching in 
more crevices, not more brands of flashlights. 

Good and Evil; Any resource or data fork whose "known" 
flag is not set to TRUE will be reported as unknown. The Good 
and Evil routines set this flag. Calls to these routines form the 
"code database", which presents a tabular appearance in the 
routines that follow. 

Don'tbe misled by thename "Good". Ichosethatasits name 
| because it's a natural antonym of Evil and also 4 letters long. It 


obviously can't know whether or not the original code from the ` 


software manufacturer contains malicious code, so it's not 
known to be “good” in that sense of the term. In the context of 
what we're doing, it actually means "trusted". 

To add the fingerprints of new trusted resources, just run the 
program againstclean disks (masters) with the report being saved 
toatextfile. After quitting the program, open the report file and 
the Fingerprint.ipas file. The MPW editor allows you to select 
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everything within a parenthesis pair by double-clicking on the 
leftorright parenthesis of the pair. Using that technique, it's very 
easy tocutand paste back and forth previously unknown resource 
fingerprints from the report file to new “IF Good(...) THEN 
EXIT;" statements in the Fingerprint.ipas file. 

SecurityPatrol runs noticeably faster if the fingerprint tests 
are done in reverse likelihood order. As far as which resources 
you mark as trusted and the order you test them is concerned, you 
have to consider what System levels the program will be run 
under, not just the level you're using for development. On the 
source code disk(s), I have included major resource fingerprints 
for Systems 4.2, 4.1 and 3.2. 

KnownDataFork: Because there isn't a TRsrcRec associ- 
ated with the data fork, this routine uses special globals, gKnown 
and gInfected. The commentary on Globals' ProcessFile, below, 
discusses what kinds of files have their data forks fingerprinted. 

LookForVirus nVIR: Did you know this virus exists in 2 
versions? The May 1988 issue of MacTutor described a 372 byte 
long version, but when I asked Howard Upchurch to send me a 
copy of nVIR, the one he sent was 422 bytes long. That was the 
strain that got onto the CD-ROM disk. Later I picked up the 372 
byte strain quite by accident at Kinko's. (Inotified the Washing- 
ton DC area Kinko's about this, incidentally.) 

LookForVirus Scores: The first 12 bytes of the Scores virus 
CODE resource is used to hold the segment and jump table 
information, which vary according to which application it's 
infecting; therefore, we skip those 12 bytes in the fingerprinting 
process. 

To shorten this article, only 
Process ADBS is shown as an example of generic Process, xxx 
routines, which include ADBS CACH, CDEF, CODE, DRVR, 
DSAT, FKEY, FMTR,LDEF, MBDF, MDEF, MMAP, NBPC, 
PACK, PDEF, PTCH, ROv#, ROvr, SERD, WDEF, XCMD, 
XFCN, boot, cdev, mppc, snth and view (if it contains methods). 
The versions on the source code disk(s) include all of them except 
CODE, which would've been more work than I could do before 
the MacTutor publication deadline. Generic routines all call 
ProcessCurrRsrc to fingerprint the resource over its entire length 
and then test only for trusted (“Good”) resources of that type. 

Special Case Process xxx's: Routines that don't fingerprint 
over the entire length of the resource, or that also test for known 
viral ("Evil") resources, are published in this article. 

Process DATA: Most innocuous DATA resources contain 
volatile data, so we default to the known flag to TRUE. The 
Scores DATA resource is simply a copy of the Scores CODE 
resource, so we also have to skip its first 12 bytes (see 
LookForVirus, Scores, above). 

Process INIT: My suspicion that the Scores INITs might 
also store data internally was confirmed when different copies of 
the same INITS yielded different fingerprints. By analyzing raw 
memory dumps, I was able to determine that they skipped over 
variable parts by means of the hardware instruction BRA We 
must also skip over these parts, or else our fingerprints will vary 
and we won't be able to recognize the INITS. 

The test for $60 is to detect the beginning of a BRA 
instruction. If the next byte is non-zero, it was a BRA.S, and we 
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| have to skip over the number of bytes in that non-zero byte. If the 


next byte is zero, we have to skip over the number of bytes in the 
extension word that follows the zero byte. 

To complicate the task of defense, future viruses may use 
other instructions to skip over variable data. Variable parts may 
be imbedded at different places in the resource, perhaps even in 
a variable way. If so, we'll just have to write tests for those 
situations too. Even if the virus succeeds at making the finger- 
print method too complicated, we will always find, thru detailed 
analysis, other identifying characteristics that we can test for. 
The advantage of bending the fingerprint technique in this case 
is the relative certainty of identification, which counter-balances 
the dangers inherent in deleting resources based on appearance. 
Yes, I agree, all of this is very tedious, but the alternative is 
vulnerability. 

Commentary on “Globals.p” 

CONSTSs: To look up the low memory global values in 
Inside Macintosh, omit the initial “k”. The kIOBufferSize 
constant is used primarily by the KnownDataFork routine in 
Fingerprintipas. Under TML II, it'S possible to use condi- 
tional compilation directives instead of the kProcessSelf con- 
stant, but the result wouldn't be TML 2.5 compatible (violating 
one of my goals). The kRsrc constants are arbitrary values used 
by InitRsrc, etc, below, to detect failure to call other Rsrc 
routines. This allows the program to display a complaint exactly 
diagnosing the problem, rather than going haywire by processing 
garbage. The values' only significance is that they're unlikely to 
occur randomly in memory. Just about any value other than 0 or 
-] will do. 

TYPEs: TCounts is used to keep counts in a consistent way; 
it's used mainly by the ListCounts routine, below. TFeedback is 
used to keep track of what was written to the screen and report 
file. JTE means "Jump Table Entry". TLoaded, TResIdOrIndex, 
TMainlItem and TMainOpt аге enumerations to make the code 
more readable; the TMain's give Main Dialog items descriptive 
names that canalso be used in indexing. TRsrcRec is used to keep 
track of everything about a resource; I didn't want to undertake 
removing infected resources unless I kept a lot of information 
about them and handled them consistently (see InitRsrc, below). 
The TScores stuff is to get the JTE in bytes 4-11 (starting from 
0) of the Scores CODE resource. TWordPtr is used just about 
everywhere. 

VARs: gAbortPatrol and the gEvt stuff are used in small 
event loops in AbortPatrollfCmdPeriodPressed апа 
AwaitKeypress. gCodeO is used during PreprocessSelf in the 
main program and whenever the current file of the patrol contains 
CODE resources. gCounts and gTotals are used to keep counts 
within a patrol and overall, respectively. The gCurr variables 
track the current file, resource, etc of the patrol; most of them are 
passed to Globals by Patrol so it can know where we are in the 
patrol, but some are set within Globals. gDisabled and gOption 
are used to communicate with the user thru the Main Dialog; if 
gDisabled is set, the corresponding option cannot be changed by 
the user. gDlogPtr is used to keep track of the DialogPtr while the 
Main Dialog is hidden (usually during a patrol). gGrafPtr is used 
to save and restore TML Pascal’s "plain vanilla"/"Textbook" 
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text window while the MainDlog is on the screen; to save 
processing, it's saved only once, in InitGlobals. gInd is used for 
consistent indention. gSecsBegins and gSecsEnds are used in 
PatrolBegins and PatrolEnds to time the wall-clock duration of 
apatrol. gSFGetPtand gSFPutPtare used tocenter the SFGetFile 
and SFPutFile in the middle of the screen. 

CallProcPtr: ProcessFile calls ProcessRsrcs with the ad- 
dress of the routine (a ProcPtr) to process each resource type; 
ProcessRsrcs has to use this INLINE to call that routine. 

AbortPatrolIfCmdPeriodPressed: The major difference 
between this routine and the one that follows is the fact that 
AwaitKeypress stops the patrol until a key is pressed, while 
AbortPatrolIfCmdPeriodPressed checks for command-period 
onthe fly. Both set the gAbortPatrol flag if command-period was 
pressed. 

AwaitKeypress: This pauses the program (like REPEAT 
UNTIL KEYPRESS, which exists under TML 2.5 but not under 
TML ID. In addition, it detects user request for cancellation 
with command-period. 

Commentroutines and Error routines: Error routines indent 
2 deep (using gInd), comments 3. Error routines also have 
significance as far as beeping and awaiting are concerned. 

DirectoryBegins: If there’s something you want to do only 
once for a volume, such as check its boot blocks, this is a good 
place to do it, subordinate to an “IF (gCurrDirId = 2) THEN". (If 
gCurrDirld is 2, you’re at the root directory of the volume.) 

FixedCode0O; The way a virus jumps back into applications 
gives us clues as to how we might repair them. So far, we’ ve been 
lucky to have JTEs lying around to repair them with (using this 
routine). In the future, who knows? Unfortunately, there’s no 
shortcut that doesn’t involve disassembly to find out how to 
restore an application. If a new virus comes along, and if you 
don’t do disassembly, but you want to code your own restoration 
code immediately, be sure to find out how to restore an applica- 
tion correctly from someone who has disassembled it. [Fake 
jump table entries is something we all should be concerned 
about. -Ed] 

InitGlobals: This routine initializes the VARs defined 
above. Note that zeroing outa BOOLEAN sets it to FALSE and 
zeroing Out a string sets it to the null string. The old way of 
centering a window or dialog was to use “screenBits.bounds”, 
but that was from the days when everyone had only 1 screen. 
Since gGrafPtr contains the “plain vanilla"/"Textbook" 
window’s GrafPtr, using gGrafPtr’.portBits.bounds will get the 
screen size of whatever screen it’s in. 

InitRsrc, GetRsrc, ReleaseRsrc and RemovedRsrc: These 
routines are a higher level interface to the Resource Manager. 
Their use cycleis InitRsrc, then GetRsrc, then, when you’re done 
with it, ReleaseRsrc or RemovedRsrc. You may then return ina 
tighter circle to GetRsrc again. If you try to use these routines in 
any order other than this, they will report an error and abort the 
program. Also, if you want to see the program crash unpredicta- 
bly, try releasing resources when processing Active Self and 
Active System. 

JTEIsValid: TML 2.5 generatesalongword compare with 
sign extension if you use $A9FO, which doesn’t compare cor- 
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rectly with the constant because it's not sign extended, hence the 
-22032. 

kForKnownViruses: This routine calls itself recur- 
sively during virus CODE removal because of the possibility of 
multiple infections. For example, an application could have 
CODEs 0 Gump table), 1 (application), 3 (Scores), 256 (nVIR) 
and 258 (Scores). As long as some infections are still being found 
and removed, I see no reason why the process should stop. 

ProcessCodes: Sometimes an application contains a CODE 
256, but isn’t infected by nVIR. Anexample is PackIt. Note that 
PackIt also skips a CODE Resld, as an application infected with 
Scores does. Which CODE do you check to see if it's infected 
with Scores? Also, I'm told that MacMoney has a CODE 
resource that's exactly 7026 bytes long, like Scores, and that 
LaserSpeed installs atpl and DATA resources into your System 
file, like Scores. 

These are the sorts of situations that made me start using 
fingerprinting in the first place, but still you have the problem of 
determining whether or not the application is actually infected. If 
a viral CODE resource is present but not linked-to by the jump 
table, then CODE 0 is not damaged, and you don't want to try to 
repair it! That would damage it! ProcessCodes calls the LookFor 
routines using the CODE resource pointed to by the first JTE. 
This greatly simplifies these otherwise confusing situations. 

ProcessCodes also looks for irregularities in the jump table 
that might signal tampering. It warns the user if the jump table 
doesn't start with the first CODE resource, or if it ever descends 
(that could signal thatan earlier resource was a new one added by 
a virus), or if it ever skips a resource ID as it ascends. (If the 
CODE resource pointed-to by the JTE stays the same, it avoids 
the test to see if JTEIsValid, which saves a considerable amount 
of I/O.) All applications infected by nVIR and/or Scores violate 
all 3 of these conditions. 

Unfortunately, applications generated by Lightspeed often 
have jump tables that violate 2 or more of these conditions. I 
don't have Lightspeed, soIcouldn'tcome up with an elegant way 
to deal with that. I'm open to suggestions. The program's 
inelegant solution is to have an exception list of applications 
whose jump tables are allowed to jump around all over the place. 
(The exception list uses the beginning of the application name in 
case there's a version number appended.) It's inelegant because 
they lose the benefit of the jump table irregularities search. They 
could get infected by some future virus and this program 
wouldn't detect anything suspicious in their jump tables. 

ProcessFile: At present, the program fingerprints the data 
forks of only MacsBug and compiler object files. The latter is to 
guard against the possibility of a virus that doesn't go away even 
after recompilation, because its original infection source is an 
altered object file. RELBs are MDS-compatible “.Rel” files and 
OBJs are MPW-compatible “.o” files. 

Also, at one time ROM patches were in the data fork of the 
System file. Now that there are PTCH resources, this may have 
been eliminated. If anyone knows whether or not the System file 
data fork can still contain executable code, please let everyone 
know by telling MacTutor. The same goes for executable code 
in any other, lesser-known file type's data fork, of course. 
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[Apple's system file data fork does indeed include executable 
code so this is another "danger" point in the system design that 
should be fingerprinted. -Ed] 

A significant amount of code is to assure that we don't open 
and close the Active Self and Active System files. If you try 
treating them like any other file, the program will probably crash. 

The Note Pad File’s data is in its data fork, and the Scrapbook 
File’s data is in its resource fork. The Scores virus adds INIT 
resources and alters their Type and Creator to conscript them for 
use with the INIT 31 mechanism documented in IM IV—256. But 
itdoesn'tthrow away their contents. (While infected, you're still 
able to use both DAs, because they continue to access those files 
by name.) That's why the program doesn't delete a file if either 
fork contains anything at all. The same deletion code will throw 
away the bogus "Desktop" and Scores files if it succeeds at 
removing all their infectious resources, incidentally. 

Finally, you may ask, why don't we search for and destroy 
nVIR's "nVIR" resources? Well, earlier (during LookFor- 
KnownViruses) it may have detected an nVIR CODE resource 
but, for some reason, was unable to restore the application. So 
far, this hasn't ever happened, but if it ever did, the program 
would not have gotten to the code that removes the nVIR 
resources. One of those, nVIR 2, contains the JTE necessary to 
fix CODE 0. Because “nVIR” resources are not in themselves 
infectious, and because empty ones can be used to inoculate 
against nVIR (see the May 1988 MacTutor), you don't want to 
delete nVIR resources willy-nilly. The only time it's really safe 
to do so is after successfully restoring an infected application's 
CODE 0. This is true in only one place (at the end of 
Disinfected_n VIR). 

ProcessRsrcs: Routines in Fingerprint.ipas decide which 
resources are infected. ProcessRsrcs takes that determination on 
faith and removes the resource if gOption[eRmVir] is on. (This 
is used as a wholesale resource type remover at the end of 
Disinfected_nVIR.) 

Also, notice that we don’t bump the index if a resource is 
removed. That’s because the resource following it now assumes 
the removed resource’s position in numerical order as far as 
GetlIndResource is concerned. This same consideration applies 
when a file is deleted. (See Patrol’s CallProcessFile discussion 
of gCurrFileDeleted, below.) 

ShortHexDump: This doesn't look right, but it is. Even 
though ‘0’ is $30 and ‘A’ is $40, you have to add $37 to get from 
10 to ‘A’. 

Commentary on “MainDlog.p” 

In order for SecurityPatrol to have no resource types except 
CODE, we have to build the Main Dialog's DITL in memory. It's 
not hard to do, keeps our private globals in synch with the dialog 
and is actually a lot of fun. Really. 

VARs: The gHdl array and gDBtnRectare used to keep from 
having to call GetDItem all the time in MainDlogWorkRe- 
quested and FrameDefaultBtn, respectively. gDBtnRect is a 
Rect inset by 4 bits to the outside of the default button’s Rect. 

ChkChk; This sets the check boxes to the values represented 
by the gOption BOOLEANS. Note that the ORD of FALSE is 0 
if and the ORD of TRUE is 1, a fact that’s also used in building 
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the DITL in InitMainDlog (to keep the Dialog Items word- 
aligned). 

FrameDefaultBtn: This routine frames the default button in 
accordance with the User Interface Guidelines chapter of Inside 
Macintosh. 

InitMainDlog: This is the routine builds the DITL, calls 
NewDialog and sets up the private globals to speed up MainD- 
logWorkRequested. The sRect and sTitle local variable arrays 
are used to build the DITL with a FOR loop; this seems wordy, 
but actually uses fewer lines than doing them linearly, and is 
much more readable and maintainable. 

KybdEquivsFilter: This routine is a filterProc to give every 
Main Dialog button and check box a keyboard equivalent. 

MainDlogWorkRequested: This is the routine that actually 
manages the Main Dialog user interface. On entry, the dialog will 
always be hidden (InitMainDlog calls NewDialog with the 
“visible” parameter FALSE, and previous calls to will have 
hidden it before exiting. BringToFront is called before Show- 
Window to keep the BringToFront from occurring visibly on 
screen and annoying the user; it doesn’t hurt anything to have an 
invisible window momentarily the front window. The WHILE 
loop manages check boxes to free up the main program from 
having to worry about those details. The DITL was built with 
check boxes after buttons, so the WHILE loop will terminate 
when a Scope Of Work button is pushed. It then returns a 
TMainItem enumeration value (defined in Globals) to tell the 
main program which scope was requested, so that it'll know 
which Patrol routine to call. 

Commentary on "Patrol.p" 

Patrol is based on code examples that have already been 
published elsewhere, notably Tech Notes 24, 66, 68, 69 and 77, 
Inside Macintosh and earlier issues of MacTutor. It adds 2 new 
features: floating a Working Directory with the scanand keeping 
files in a directory together. Floating a Working Directory is to 
avoid overflowing 255 characters of partial pathname if the 
directories are deeply nested. (A virus creator might deliberately 
hide a virus deep in a series of nested folders to rely on other anti- 
virus utilities’ possible reliance on full pathnames. Such a virus 
could very easily be launched by a document at the root level.) 
I’ve tested the floating Working Directory feature to 52 levels 
deep of nested folders, each with 3 1-character-long folder names 
and different filenames in each folder. As for keeping files in a 
directory together, previous directory scan algorithms were set 
up to recursively scan subdirectories right in the middle of the 
files being scanned, so you would see files from the parent 
directory, then files from a child directory, then more files from 
the parent directory, etc. Patrol doesn't go to subdirectories until 
it has patrolled all files in the current directory. This also 
minimizes opening and closing Working Directories. 

kPatsInitd: This is anarbitrary value used by Patrol routines 
to detect failure to call InitPatrols. This allows the program to 
display a complaint exactly diagnosing the problem, rather than 
going haywire by processing garbage. The value's only signifi- 
cance is that it's unlikely to occur randomly in memory. Just 
about any value other than O or -1 will do. 

TOverlappingPBs: For reasons unknown, Apple chose to 


266 


define a wide variety of parameter blocks with mostly-the-same/ 
sometimes-different field names. For the limited uses in Patrol, 
the only major difference between HParamBlockRec in CIn- 
foPBRec is whether or not you'recalling PBGetCatInfo. Rather 
than continually moving data around to keep their fields in synch, 
this TYPE allows defining PBs with which both types' field 
names can be used. This has been okay (so far) because the only 
PB values that Patrol uses happen to match up between the 2 
types. Occasionally it can be a bit confusing, but it keeps field 
name usage usually correct. 

VARs (private): gAppDirld and gAppVRefNum are used to 
detect "Active Self". gInitdFlag is used with kPatsInitd (see 
above) to detect failure to call InitPatrols. gOnly1Deep is used 
in PatrolDir to avoid processing subdirectories when the Scope 
Of Work is Directory (singular). gOrigWDRefNum is used to 
remember the wdRefNum of the first directory of the patrol (see 
FloatWDDeeper and FloatWDShallower, below). gPBs is used 
to do the Low Level File Manager calls to do the patrol itself. 
gSFLst is passed to the SFGetFile dialogs in PatrolDirectories 
and PatrolFiles. gSysDirId and gSysVRefNum are used to detect 
"Active System". gWDPBRec is used by FloatWDDeeper and 
FloatWDShallower to open and close working directories. 

BuildDirname: This routine is called only when the current 
directory being patrolled changes. It uses a local variable of type 
TOverlappingPBs (see above) so as not to disturb the values in 
gPBs, which is still being used by the patrol. Starting from the 
new current directory (as pointed to by gCurrWDRefNum), it 
works backwards to the root directory of the volume; for ex- 
ample, if the new current directory is “A:B:C:”, it would build 
“С”, then “B:C:”, then “A:B:C:”. ioFDirIndex is set to -1 
because we're getting info about directories. (How to set 
ioFDirIndex is documented in Tech Note #69.) Initializing the 
loop by setting ioDrParID to 0 has no direct effect on the 
PBGetCatInfo call, because that's a field that's returned by the 
File Manager. Instead, it's being used in combination with 
"joDrDirID := 10DrParID;” to set ioDrDirID to 0, which does 
affect the PBGetCatInfo call. (It will start the loop at the 
directory pointed-to by ioVRefNum, not some other directory on 
the same volume.) This may seem like a roundabout way to start 
getting folder names at gCurrWDRefNum, but the same line 
("ioDrDirID := ioDrParID;") continues the loop upward thru the 
folder hierarchy, so it's actually pretty straightforward. The loop 
proceeds until ioDrDirID is 2, signifying the root directory of the 
volume. (Note that this works correctly even if 
gCurrWDRefNum points to a root directory, since the File 
Manager also returns ioDrDirID; the loop will have exactly one 
pass, beginning with ioDrDirID equal to 0 and ending with it 
equalto2.) Theroutine simply terminates if an error occurs, such 
as gCurrDirname overflow. This is relatively acceptable because 
the program never uses the pathname to access a file during a 
patrol; instead, it uses gCurrWDRefNum and gCurrFilename to 
access the file, and treats gCurrDirname as commentary for the 
user. InitSecurityPatrol in the main program uses gCurrDirname 
in the ReWrite that creates the report file. This is unfortunately 
necessary because there isn’t a parameter for a wdRefNum in the 
ReWrite statement. On the bright side, the user is unlikely to 
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place the report file more that 255 characters of full pathname 
deep. 

CallProcessEile: Patrol centralizes all calls to ProcessFile 
via this routine to make absolutely sure that gActiveSelf and 
gActiveSys get set properly and that gCurrFileDeleted gets reset 
to FALSE. Correctly setting gActiveSelf and gActiveSys every 
time is vital to keep Security's ProcessFile routine from closing 
their resource forks. Resetting gCurrFileDcleted to FALSE 
every time is vital to prevent skipping the file following the one 
deleted, which would assume the numerical position of the 
deleted file within the patrol (pointed to by ioFDirIndex). 

FloatWDDeeper and FloatWDShallower (similarities): 
The problem with using pathnames to access files is the fact that 
you have only 255 characters to name it with. Since filenames 
and folder names can be up to 31 characters long, it's possible to 
overflow that limit with folders nested only 8 deep.. Patrol gets 
pastthis problem by “floating” a working directory. As a general 
rule, both of them close the working directory pointed-to by 
gCurrWDRefNum, use a Dirld to open another working direc- 
tory, and put the new wdRefNum into gCurrWDRe(íNum. The 
difference is what the newly created working directory repre- 
sents. 

FloatWDDeeper: This routine creates a working directory 
to move from a parent directory to a subdirectory using the DirId 
encountered in the patrol (namely, gPBs.fCPBRec.ioDrDirID). 

FloatWDShallower: This routine creates a working direc- 
tory to return from a subdirectory to its parent. To do this, 
FloatWDShallower could use an ioDrParlId returned by PBGet- 
CatInfo (see BuildDirname, above), but there's a much simpler 
method. PatrolDircalls itself recursively,so whenitreturns from 
patrolling a subdirectory, its pDrDirId parameter automatically 
reverts to the DirId of the parent. FloatWDShallower uses this 
more readily available value. 

FloatWDDeeper апа FloatWDShallower (exception): The 
only exception to the rule relates to the start directory of the 
patrol. If it's the root directory, PatrolDir starts out with a true 
vRefNum, not a wdRefNum. This is documented in Tech Note 
#77, which seemed to be warning us never to pass a vRefNum to 
PBCloseWD. (It didn't say so explicitly, but I haven't tried it to 
see what would happen. To get around this problem, 
FloatWDDeeper makes an exception at the start of the floats 
(leaving the start directory open) and FloatW DShallower makes 
an exception at the end (restoring the start directory with gO- 
rigWDRefNum). 

GetActualDirId: This routine assures that gCurrDirld will 
always be accurate, even when PauolDir is called with pDrDirld 
equal to O. Even though Globals doesn't currently usc 
gCurrDirld, Patrol uses it to detect the Active Self and Active 
System. 

InitPatrols: This routine makes sure that all of Patrol's 
globals are properly initialized. The ZeroFillRange calls implic- 
itly setall BOOLEAN variables to FALSE, all strings to the null 
string and all ioCompletion fields to NIL. Using KFSFCBLen to 
see if HFS is active is documented in Tech Note #66. Calling 
GetVRefNum to get gSysV RefNum is documented in Tech Note 
#77. Calling PBHGetVInfo and referencing io VFndrInfo[1] to 
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get gSysDirld is documented in Tech Note #67. Referencing 
kBootDrive instead if HFS is not active is also in #77. 

PatrolDir: This routine is the heart and soul of Patrol. Its 
techniques are documented in Tech Note #69. If you understand 
that, you'll understand this, but PatrolDir’s way of doing things 
is considerably different. It patrols files first (ignoring subdirec- 
tories), then patrols subdirectories (ignoring files). Patrolling 
files uses PBGetFInfo (note: not PBHGetFInfo). Patrolling 
subdirectories uses PBGetCatInfo. There are three major advan- 
tages of doing it that way: 

(1) filenames appear in an unbroken list, 

(2) the program can work even if HFS isn't active, 

(3) it's easier to patrol only 1 directory deep. 

There are other differences from Tech Note #69: It calls 
FloatWDDeeper, FloatWDShallower and GetActualDirld, for 
reasons discussed above. Also, if gError «» NoErr after a 
recursive call, it backs out of the recursion rapidly until it reaches 
the start directory of the patrol; this saves a lot of unnecessary 
calls to FloatWDShallower, since doing only the last one has the 
same effect as doing them all. 

PatrolFiles: I've gone to considerable trouble here to cor- 
rectly call DirectoryEnds and DirectoryBegins whenever the 
user selects a file in a different directory from the previously 
selected file. That's the purpose of the imbedded procedure 
CallPrevDirEnd. If you don't go to that trouble, the TFeedback 
variables in Globals won't get reset properly and the new direc- 
tory name won't get displayed on the screen nor in the report file. 

Commentary on "SecurityPatrol.p" 

SecurityPatrol uses standard Pascal text I/O to report its 
findings and progress to the user. (In TML terminology, the TML 
2.5 version is called a “plain vanilla application" and the TML II 
version is called a “Textbook application".) The main program 
also manages initialization, termination and high-level interface 
between MainDlog and Patrol. 

Because there's no event loop, the program doesn't support 
DAs (оп-ригроѕе). Italsospecifically disables FKEYs. The only 
form of concurrent code that it doesn’t disallow is MultiFinder, 
but you shouldn’t run it under MultiFinder anyway, because you 
won't be able to examine open files, such as the DeskTop file and 
the concurrent applications themselves (the Finder, eg). 

There's a very good reason why I don't like the idea of 
concurrently executing code. Let me give you a hypothetical 
scenario: Suppose someone imbedded a virus in a WDEF and 
installed that WDEF into the DeskTop file of adisk. Idon'tknow 
how the Finder does things, but suppose it allows a runtime 
override of definition procedures using the standard Resource 
Manager precedence (document — application —> System 
filc). You're patrolling files in foreground under MultiFinder, 
you get an SFGetFile dialog to patrol Directories, and you insert 
the infected disk. In background, the Finder reads the DeskTop 
file of the disk and display's the disk' s window behind the 
SecurityPatrol window using the override WDEF. You've just 
been infected, and SecurityPatrol hasn't even had a chance to 
look at the disk yet. My guess is that the published version of 
SecurityPatrol wouldn't find anything on that disk. Whether or 
not your version would is up to you. 
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Of course, that scenario relies on a presupposition that the 
Finder allows a runtime override of WDEFs, which it probably 
doesn’t do. On the other hand, I don’t know for sure that it 
doesn’t, and I don’t like the uncontrolled variable it represents. 
Even if the Finder wouldn’t let a virus thru this way, maybe some 
other concurrent application or DA would. I didn’t go extraor- 
dinarily out of my way to prevent all concurrent code (VBLs, 
AppleTalk, etc), but I suspect there’s a security hole there 
somewhere. I’m voicing my concern here to focus more minds 
than my own on the subject. [Apple has also thought of this 
problem and is working on it presently. They just don't want the 
wrong kind of minds to be focused on it, if you know what I mean! 
-Ed] 

“(QUTPUT)”; The presence of this phrase in the program 
header tells TML 2.5 that this is a “plain vanilla" application. 
Before the main procedure starts to execute, the runtime library 
will initialize all the managers it needs for text I/O, create the 
WriteLn window and put “TML Pascal” into its drag bar title. 
Because it initializes the managers, we don't. It's ignored by 
TML II. 

kPreprocessSelf and kAwaitVerification; Having kPre- 
processSelf turned on can get to be a real nuisance during 
development, but it'S an important safeguard and better than 
processing Active Self during the patrols. You may want to turn 
it off during development and back on again in the final cleanup 
before release to your friends and/or company's users. The code 
controlled by kAwaitVerification will be cleaned up in Version 
2.0: All of SecurityPatrol’s own CODE resources except the one 
containing Fingerprint.ipas should be fingerprinted and tested in 
Fingerprintipas. The verification task presented to the user 
could then be made much simpler. 

. SerDmpEnbPtr and ScrDmpEnbSave: These are used in 
InitSecurityPatrol and ExitSecurityPatrol to save, disable and 
restore FKEYs. 

(52%): A TML 2.5 to TML II upgrade issue not mentioned 
in the TML II manual's Appendix F is the fact that main 
program's routine names, when referenced from a UNIT, will not 
be found at Link time unless you explicitly define them exter- 
nally with this directive. It's documented in Appendix C, but not 
as a difference. 

InitSecurityPatrol: Textbook is a TML II routine in 
PasLibIntf, distributed by TML Systems with the compiler. It 
initializes all the managers it needs for text I/O, creates the 
WriteLn window and puts the application's name into its drag bar 
title. Without it TML II would WriteLn all over the desktop. 
Because it initializes the managers, we don't. For TML 2.5 
users, a dummy version of Textbook is defined in the 
PasLibIntf.Pas UNIT on the source code disk(s). 

The initial values of the Main Dialog check boxes are sct 
between the calls to InitGlobals and InitMainDlog. 

When AppleTalk is not active, the statement 
"ReWrite(o, PRINTER:’)” is used to send the report file to the 
printer. Under TML 2.5, this prints to a direct-connect 
ImageWriter on serial port B in streaming text modc, which is 
even more draft than draft mode (the ImageWriter doesn't 
recognize curly quotes, for example). Under TML II, this 
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feature doesn't work, and the report file output will be, in effect, 
thrown away. Tom Leonard is working on the problem. In the 
meantime, you can save the report to a text file and print it later 
with MPW, which has the distinct advantage of also being able 
to print to a LaserWriter. 

TML 2.5 allows TextFace calls to affect the WriteLn output. 
TML II doesn't, but it doesn't hurt. 

PreprocessSelf; These are the most stringent tests I could 
think of to guard against the program's own infection. You're 
invited to add more. If you leave in the line that turns on 
gOption[eRmVir], the program will disinfect itself of all viruses 
it knows how to remove. If you take out that line, it will detect 
known viruses and abort, so you should tell your users always to 
run it from a write protected disk. 

TML 2.5 Link puts a JMP d(PC) instruction at the beginning 
of CODE 1 that jumps into the actual start address of SecurityPa- 
trol. That's why itchecks for $4EFA and offsets by the extension 
word that follows. TML  IIis unaffected by this test. 

Wryte routines: These routines manage text I/O. Under 
TML 2.5, Write, WriteLn, etc, can only appear in the main 
program, not in UNITs. This limitation was done away with in 
TML П, but this way of doing things is compatible. Moreover, 
by centralizing output, it allows calling PLFlush on every 
WriteLn. 

PLFlush isa TML П routine in PasLibIntf. (See “(ООТ- 
PUT)", above.) It flushes a file's buffer. “PLFlush(OUTPUT);” 
assures that screen feedback will be current. Alternatively, you 
could call "PLSetVBuf (OUTPUT, NIL, $40, 256);" in InitSecu- 
rityPatrol, but I like this stick-shift level of control, and it seems 
to work a little better. 

TML 2.5 used to print numbers with a default field width of 
1. TML II now uses the ANSI-standard Pascal default field width 
(6, I think). To avoid inconsistent results between the 2 versions 
of the program, WryteNbr never uses the default field width, but 
instead specifies ficld width explicitly. 

zz3ecurityPatrol; See the end of the commentary on 
CodeSizeLimits.p, above. 


The source code disk for this issue (see the MacTutor Mail 
Order Store Ad) contains both the TNL 2.5 and TML II versions 
with the complete system file resource fingerprints for previous 
system files. We recommend purchase of this disk, only $8! 


( Copyright Header 

91988 by Steve Seaquist. All rights reserved. Used by 
permission. Use at your own risk. No warranty is expressed 
or implied. Neither Apple Computer nor MacTutor endorse or 
warrant this program in any way, nor are they responsible for 
its use or mis-use in any way. 

This Macintosh virus-detecting program was originally pub- 
lished and explained in the February 1989 issue of MacTutor 
magazine. Some aspects of its design are important to 
security, and it uses some unusual techniques, so please read 
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*CodeSizeLinits.p^ 
UNIT CodeSizeLimits; 
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INTERFACE 
VAR 
gJTS ize: 
gEntryPoint : 
gSizeLimit: 
ARRAY [9..8] OF 
gMaxCode : 


IMPLEMENTATION 


PROCEDURE zzSecurityPatrol; 


INTEGER; 
LONGINT; 


LONGINT; 
INTEGER; 
PROCEDURE GetCodeSizeL imits; 


EXTERNAL ; 


PROCEDURE GetCodeSizeLimits: 


BEGIN 
gEntryPoint 
gJTSize 
gMaxCode 
gSizeLimit[0] 
gSizeLimit[1] 
gSizeLimit[2] 
gSizeLimit[3] 
gSizeLimit[4] 
gSizeLimit[5] 
gSizeLimit[6] 
gSizeLimit[7] 
gSizeLimit[8] 

END; 

END. 


ORD4C8zzSecur i tyPatro12*$1A; 
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S JTS ize + 16; 
15700; 
23900; 
11200; 
00844; 
01908; 
01606; 
01822; 
01312; 


“Fingerprint. ipas’ 


(File Fingerprint. ip 
VAR 


as ) 


gFgPr 1, gFgPr2, gFgPr3, gFgPr4, gFgPr5, gFgPr6, gFgPr : 
PROCEDURE CommentFgPr ; 


BEGIN 
Wryte e 


(5; 

WryteNbr (gFgPr 1,5); 
WryteChart', ^2; 
WryteNbr CgFgPr2,9); 
WryteChar(C', ^); 
WryteNbr CgFgPr3,62; 
WryteChart', ^); 
WryteNbr CgFgPr4,5); 
WryteChar(C', ^); 
WryteNbr (gFgPr5,5); 
WrgteChart ', ^2; 
WryteNbr CgFgPr6,5); 
WryteCharC', ^); 
WryteNbr CgFgPr7,9); 


WryteChart( 272; 
END; 
R men 

BEGIN 
ErrorBegins( ‘Unknown data fork’); 
CommentFgPr ; 
ErrorEnds(@); 
END; 
PROCEDURE | CommentFgPrRsre(pRsrcPtr: TRsrcPtr); 
BEGIN 
IF (gFgPrTitle © °’) THEN 

BEGIN 

ErrorMsg(gFgPrTitle,0); 


gFgPrTitle := °’; 
END; 


CommentRsrcBegins(pRsrcPtr ); 


CommentFgPr ; 
WryteEoln; 
END; 
FUNCTION — Evil 
Cpl, p2,p3: LONGINT) 
BOOLEAN; 
BEGIN 
Evil := FALSE; 
IF (gFgPri = 
AND (gFgPr2 = p2) 
AND CgFgPr3 = p3) THEN 
WITH gCurrRsrc DO 


( 
ie 
( .. 
( 
( .. 
( .. 
( 


Edited so that .. 


) 
calls fit into . 42) 
MacTutor column. ) 
width. Source .. ) 
code disk .. ) 
version tests.  ) 
all gFgPr's. ) 
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LONGINT; 


BEGIN 
Evil ‚= TRUE; 
fKnown ‚= TRUE; 
fInfected := TRUE; 
ginfected := TRUE; 
END; 
END; 
PROCEDURE FoPr(pPtr: Ptr; pSize: Size); 
VAR 
i,sTemp: LONGINT; 
sWordPtr : TWordPtr; 
PROCEDURE  FgPrTemp; 
BEGIN 
gFgPr2 := gFgPr2 + sTemp; 
gFgPr3 :- BXor(gFgPr3,sTemp?; 
gFgPr4 := gFgPr4 + ORDCODDCsTemp 22; 
gFgPrb := gFgPr5 + ORDCsTemp« 0); 
gFgPr6 := gFgPr6 + ORDCsTemp? 0); 
IF 0DD(i) THEN 
gFgPr7 := gFgPr7 + sTemp 
ELSE 
gFgPr7 := gFgPr7 - sTemp; 
END; 
BEGIN 
sWordPtr := TWordPtr(pPtr); 
FOR i := 1 TO (pSize DIV 2) 00 
BEGIN 
sTemp := ORD4CsWordPtr*); 
FgPrTemp; 


INCCLONG INTCsWordPtr 22; 
INCCLONGINTCsWordP tr 2); 


END; 
IF ODDCpSize) THEN 
BEGIN 
sTemp := BAndCORD4CsWordPtr^ 2, $FF00); 
FgPrTemp; 
END; 
gFgPri := gFgPr] + pSize; 
END; 
FUNCTION _ Good ( Edited so that . 
(p1, p2,p3: LONGINT) ( .. calls fit into .. 
BOOLEAN; ( .. MacTutor column.. 
BEGIN ( width. Source .. 
Good := FALSE; ( .. code disk .. 
IF (gFgPri = pl) ( .. version tests.. 
AND CgFgPr2 = p2) ( .. a1] 7 gFgPr's. 
AND (gFgPr3 = p3) 
AND CgFgPr4 = p4) 
AND (gFgPr5 = p5) 
AND CgFgPr6 = рб) 
AND (gFgPr7 = p7) THEN 


WITH gCurrRsrc DO 
BEGIN 
Good 
fKnown 
гесе: 


TRUE; 
TRUE; 
FALSE; 


о 
е; 
Te) 
5 -0 
= 
pou 

"вит ип H H 


BOOLEAN; 


sButesRemaining: LONGINT; 

sBytesThisPass:  LONGINT; 

PROCEDURE  KnownIF 
(p1,p2,p3,p4,p5,p6,p7: LONGINT); 


w Ringe aae `v. `v. uasa “чу? 
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BEGIN 


IF (gFgPri = p1) 
AND CgFgPr2 = p2) 
AND (gFgPr3 = p3) THEN 
EXITCKnownDataFork2; 
END; 
BEGIN 
KnownDataFork := TRUE; 
InitFgPr; 


sBytesRemaining := gCurrE0F; 
WHILE sBytesRemaining > 0 DO 
BEGIN 


IF (sBytesRemaining > kIOBufferSize) THEN 


sBytesThisPass := kl0BufferSize 
ELSE 

sBytesThisPass := sBytesRemaining; 
gError :- FSRead(gCurrRefNum, 

sBytesThisPass, 
gCurrIOBuf fer); 
IF (CgError © NoErr) THEN 

BEGIN 

Еггог05Егг( ‘Couldn’t read data fork’); 

EXITCKnownDataFork); 

END; 
FgPrCgCurrIOBuf fer, sBytesThisPass); 
sBytesRemaining := 

sBytesRemaining - sBytesThisPass; 
END; 


KnownIFC 512, 1888894, 23566); (DRVRRunt ime) 
KnownIF (34304, 122743292, -30316); (Interface) 


KnownIF( 2560, 9884035, - 13755); (0bjL ib) 


KnownIFC 8704, 38905655, -5215); (PerformL ib) 


Кпонп1Ғ(22016, 115306063, 12985); (Runtime) 
KnownIF( 6656, 28028083,-227092; (Tooll ibs) 
KnownIFC 3072, 12526030,-25732); (HyperXCMD) 
KnownIFC 2560, 11236115,-31819); (SANEL ib) 


KnownIF( 4608, 16761354,- 16062); (SANEL 1881) 


KnownIF( 15872, 62109326,- 18394); (TMLPasL ib) 


KnownIF (27634 , 204583778, -8384); (MacsBug 5.5) 


KnownDataFork := FALSE; 


END; 
PROCEDURE — LookForVirus.nVIR; 
BEGIN 


IF (gCurrRsrc.fResId <> 256) THEN 
EXITCLookForVirus_nVIR); 
gCurrRsrc.fInfected := TRUE; 
ProcessCurrRsrc; 
IF Evil€ 372, 1334566,-15078) THEN EXIT; 
IF Evil€ 422, 1445005,-22T175) THEN EXIT; 
END; 
R гҮј r 
BEGIN 
IF (gCurrRsrc.fSize < 7026) THEN 
EXITCLookForVirus_Scores); 
InitFgPr; 
FgPr(PtrCORDACgCurrRsrc .fHdl^2*122,7014); 
IF gOptionteFgPr] THEN 
BEGIN 
gFgPrTitle := ‘Short fingerprint’; 
CommentFgPrRsrc(@gCurrRsrc); 


END; 
IF EvilC 7014, 32071691, 16777) THEN EXIT; 
END; 
PR R rrRsrc; 
BEGIN 
InitFgPr; 


FgPrCgCurrRsrc.fHdl^,gCurrRsrc .f Size); 
END; 


PROCEDURE . ProcessRemoveRsrc; 
BEGIN 
gCurrRsrc . fKnown := TRUE; 
gCurrRsrc.fInfected := TRUE; 
END; 
PR P 
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BEGIN 
ProcessCurrRsrc; 
IF Good€ 262, 946915, -549) THEN EXIT; 
END; 
PR R r 
BEGIN 
WITH gCurrRsrc DO 
BEGIN 


fKnown := TRUE; 
IF (fSize < 7026) THEN 
ЕХІТСРгосеѕѕ DATA); 
InitFgPr; 
FgPrCPtrCORDACÉHd1^2* 12), 7014); 
IF gOptionteFgPr] THEN 
BEGIN 
gFgPrTitle := ‘Short fingerprint’; 
CommentFgPrRsrcCégCurrRsrc?; 
END; 
END; 
IF EvilC 7014, 32071691, 16777) THEN EXIT; 
END; 
r. 
VAR 
sOffset: INTEGER; 
sPtr: Ptr; 
BEGIN 
WITH gCurrRsrc DO 
BEGIN 
InitFgPr; 
IF (fResId = 6) 
OR ((fResId = 10) 
AND CgCurrFilename € “ Vaccine’)) 
OR CfResId = 17) THEN 


BEGIN 

sOffset := 0; 

sPtr := fHdl^; 

IF (sPtr* = $60) THEN 
BEGIN 
INCCLONGINTCsPtr)); 

IF (sPtr^ = 0) THEN 
BEGIN 
INCCLONGINTCsPtr)); 
sOffset := 2 + TWordPtr(sPtr)°; 
END 

ELSE 
sOffset := 2 + sPtr^; 

END; 


FgPrCPtrCORDACfHd1^ 255077660, 
fSize-sOffset); 
IF  gOptionteFgPr)] THEN 
BEGIN 
gFgPrTitle := ‘Short fingerprint’; 
CommentFgPrRsrc(@gCurrRsrc); 
END; 


FgPrCfHdl^,fSize); 

END; 

IF GoodC 2234, 5918345, 24783) THEN EXIT; 
IF Good( 2, 20085, 20085) THEN EXIT; 
IF Good€ 580, 2390534, -3964) THEN EXIT; 
IF Good€ 256, 624295,-11467) THEN EXIT; 
IF Good€ 276, 821588,-22226) THEN EXIT; 
IF Good€ 318, 1106224, 15474) THEN EXIT; 
IF Good€ 372, 1325194, 13502) THEN EXIT; 
IF Good€ 262, 889886,-25106) THEN EXIT; 
IF Good( 5200, 16204911,-21859) THEN EXIT; 
IF Good€ 514, 2113878,-13890) THEN EXIT; 
IF Good€ 264, 920108, -860) THEN EXIT; 
IF Good( 436, 1746895, -3577) THEN EXIT; 
IF Good€ 358, 1167886, 15360) THEN EXIT; 
IF Good€ 26, 102477, -9939) THEN EXIT; 
IF Good€ 944, 3348718,-13868) THEN EXIT; 
IF Good€ 820, 2799973,-29445) THEN EXIT; 
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IF бооас 572, 


IF EvilC 366, 
IF Evil€ 416, 
IF Evil€ 758, 
IF EvilC 1014, 
IF Evil€ 474, 
END; 


BEGIN 


1840164, -5246) THEN EXIT; 


1333 180,-29162) THEN EXIT; 
1443619, -5115) THEN EXIT; 
3291138, 6608) THEN EXIT; 
4600985, 19785) THEN EXIT; 
1932041, 18387) THEN EXIT; 


TLoaded =CeNotYet, eAlreadyLoaded, eWeLoadedIt); 
TMainItem = 
CeNotADlogI tem, 
eDirs,eDiry, eEvery,eFiles, eQuit, 
eAwait,eBeeps,eFgPr,eFgPrC, 
eLList,eRmVir,eTrace, 
eMain,eOpts,eScOW, 
eDBtn); 
TMainOpt = ARRAY [eAwait..eTrace] OF BOOLEAN; 
TPaocRec = PACKED ARRAY[1..1)] OF CHAR; 


ProcessCurrRsrc; 
IF Good( 4874, 17745131, 2851) THEN EXIT; 


IF EvilC 2410, 10235053,-25635) THEN EXIT; 
END; 


*Globals.p* 
UNIT Globals; 
INTERFACE 
USES 
MemTypes, QuickDraw,OSIntf,ToolIntf, PackIntf; 
CONST 
(— Low Men Globals —) 
kCurApName - $910; 
kCurApRefNum = $900; 
kBootDr ive = $210; 
kResLoad = $A5E; 
kScrDmpEnb = $2F8; 
kSFCBLen = $3F6; 
kSPConf ig = $1FB; 
kSysMap = $458; 
kSysResName = $AD8; 
(— Other constants — 
kIOBufferSize - 10000; 
kProcessSelf - FALSE; 
kRsrcHdlValid - 9876543; 
kRsrcIsInitd = 3456789; 
kZeroOutVirs - TRUE; 
TYPE 
TCountsPtr = ^TCountsRec; 
TCountsRec = 
RECORD 
fDeleted: LONGINT; 
fExamined: LONGINT; 
fFiles: LONGINT; 
f Infected: LONGINT; 
fRemoved: LONG INT; 
fResources: LONGINT; 
END; 
TFeedbackPtr = ^TFeedbackRec; 
TFeedbackRec - 


PACKED RECORD 
fWroteDirname: BOOLEAN; 
fWroteFilename: BOOLEAN; 


END; 
TJTEHd] = ^TJTEPtr; 
TJTEPtr - ^TJTERec; 
TJTERec = 
RECORD 
fOffset: INTEGER; 
fSkip3F3C: INTEGER; 
fSegId: INTEGER; 
fSkipA9F0: INTEGER; 
END; 
TJTHdl = ^TJTPtr; 
TJTPtr = ^TJTRec; 
TJTRec x 
RECORD 


fAboveAbS ize: LONGINT; 
fBelowA5Size: LONGINT; 
fNbrBytesInTable: LONGINT; 


fTableOffset: LONGINT; 
fJTEntry: 

ARRAY (1..1) OF TJTERec; 
END; 
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TResId0r Index = (ResId, Index); 
TRsrcPtr = “TRsrcRec; 
TRsrcRec = 
RECORD 
fFlag: LONGINT; 
fHdl: Handle; 
f Infected: BOOLEAN; 
fKnown: BOOLEAN; 
fLoaded: TLoaded; 
fResAttrs: INTEGER; 
fResId: INTEGER; 
fResType: ResType; 
fSize: Size; 
fState: SignedByte; 
END ; 
TScoresHdl - *TScoresPtr; 
TScoresPtr - ^TScoresRec; 
TScoresRec = 
RECORD 
fOffsetToFirstJTE: INTEGER; 
fNbrJTEsForRsrc: INTEGER; 
fOldJTE: TJTERec; 
END; 
TWordHdl - ^TWordPtr; 
TWordPtr = ^[NTEGER; 
VAR 
gAAGlobals: SignedByte; 
gAbor tPatrol,gActiveSelf,gActiveSys: BOOLEAN; 
gCoded : TRsrcRec; 
gCounts: TCountsRec; 
gCurrDInfo: DInfo; 
gCurrDirId,gCurrEOF: ^ LONGINT; 
gCurrDirname: 917255; 
gCurr IOBuf fer: Ptr; 
gCurrFileDeleted: BOOLEAN; 
gCurrF i lename: 517255; 
gCurrF Info: FInfo; 
gCurr Index: INTEGER; 
gCurrRef Num: INTEGER; 
gCurrRsrc: TRsrcRec; 
gCurr VRef Num: INTEGER; 
gCurr WDRef Num : INTEGER; 
gDateTimeRec: DateT imeRec; 
gDisabled: TMainOpt; 
gDlogPtr: DialogPtr; 
gError : 05Егг; 
ДЕУІ: EventRecord; 
gEvtMask : INTEGER; 
gFgPrTitle: 5іг255; 
gGrafPtr: GrafPtr; 
gHFS: BOOLEAN; 
gInd: STRING( 181; 
gInfected: BOOLEAN; 
ginfectedWritten: BOOLEAN; 
gOption: TMainOpt; 
gPgnrname : 517255; 
gRepor tF lags: TFeedbackRec; 
gScreenF lags: TFeedbackRec; 
gSecsBegins: LONGINT; 
gSecsEnds: LONGINT; 
gsFGetPt: Point; 
gSFPutPt: Point; 
gSFRep: oFRep ly; 
gTotals: TCountsRec; 
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gZZGlobals: SignedByte; R 
FUNCTION Code@IsValid: BOOLEAN; BEGIN 
PROCEDURE CommentBegins; WHILE TRUE DO 
PROCEDURE CommentFgPrRsrc(pRsrcPtr: TRsrcPtr); BEGIN 
PROCEDURE CommentRsrcBegins(pRsrcPtr: TRsrcPtr); IF NOTCGetNextEvent(gEvtMask,gEvt)) THEN 
PROCEDURE DirectoryBegins; CYCLE; 
PROCEDURE DirectoryEnds; WITH gEvt DO 
PROCEDURE ErrorBeginsCpStr: $tr255); IF (what = keyDown) THEN 
PROCEDURE ErrorEnds(pBeeps: ^ INTEGER); BEGIN 
PROCEDURE ErrorOSErr(pStr: 517255); IF (BAnd(modifiers,cmdKeu)=cmdKeu) 
PROCEDURE GetRsrc AND СВАлаСтеѕѕаде, charCodeMask )=$2E ) 
CpRsrcPtr: TRsrcPtr; THEN 
pResType: ResType; BEGIN 
pint: INTEGER; gAbortPatrol := TRUE; 
pIntIs: TResIdOr Index); WryteLnC'Patrol aborted’); 
PROCEDURE InitGlobals; END; 
PROCEDURE  InitRsrc(pRsrcPtr: TRsrcPtr); LEAVE; 
FUNCTION — JTEIsValidCpJTEPtr:  TJTEPtr): BOOLEAN; END; 
PROCEDURE ListCounts(pPtr: TCountsPtr); END; 
PROCEDURE  LookForKnownViruses; END; 
PROCEDURE PauseBrief ly; FUNCTION — CodeZIsValid: BOOLEAN; 
PROCEDURE PatrolBegins; BEGIN 
PROCEDURE PatrolEnds; IF gOption[eTrace] THEN 
PROCEDURE ProcessCurrRsrc; Trace( Code IsValid'); 
PROCEDURE  ProcessF 11е; WITH TJTHdlCgCodeQ .fHd12^^ 00 
PROCEDURE ReleaseRsrc(pRsrcPtr: TRsrcPtr); Code@IsValid := 
PROCEDURE ShortHexDump(pPtr: Ptr;pNbrBytes: SignedByte); (gCode£ .f Size y= 24) AND 
PROCEDURE  Trace(pStr: біг255); CfAboveA5Size >= 40) AND 
PROCEDURE TraceNbr(pStr: Str255; pNobr : LONGINT); CfNbrBytesInTable >= 8) AND 
PROCEDURE ZeroOut(pStart: Ptr;pCount: Size); (fTableOffset = 32) AND 
PROCEDURE — ZeroOutRange(p1: Ptr;p2: Ptr); (fAboveA5Size = fNbrBytesInTable*32) AND 
IMPLEMENTATION (CfNbrBytesInTable MOD 8) = 0); 
($R-) END; 
PROCEDURE ExitSecurituPatrol; EXTERNAL; PROCEDURE CommentBegins; 
PROCEDURE Wryte(pStr: 57255); EXTERNAL; BEGIN 
PROCEDURE WryteChar(pChar : CHAR); EXTERNAL; Wryte(gInd); 
PROCEDURE WryteEoIn; EXTERNAL ; WryteCgInd); 
PROCEDURE  WryteF ilename; EXTERNAL; WryteCgInd); 
PROCEDURE WryteF ilenameToScreenOnlyForNow; EXTERNAL; END; 
PROCEDURE WryteLn(pStr: 5іг255); EXTERNAL; PROCEDURE CommentRsrcBeginXpRsrcPtr: TRsrcPtr); 
PROCEDURE  WryteNbrCpNbr :LONGINT;pNbrÜ igi ts: INTEGER); EXTERNAL; BEGIN 
PROCEDURE WryteTypeCpType: ResType); EXTERNAL; CommentBegins; 
PROCEDURE CaliProcPtr(pProcPtr: ProcPtr); WITH pRsrcPtr^ DO 
INLINE BEGIN 
$205F , ( MOVE.L (А72%,А0 ) WryteType(fResType); 
$4E90; (JSR CAB) ) WryteNbr CfResId, 7); 
PROCEDURE ErrorInfected Wryte 997 
(pStr: 917255); FORWARD; Shor tHexDump(P tr CORD4C8f ResAttrs?* 12, 1); 
PROCEDURE ErrorMsg(pStr :Str255; pBeeps: INTEGER); FORWARD; WryteCharC' 2^); 
FUNCTION  FixedCode8CpJTPtr: — TJTEPtr2: BOOLEAN; FORWARD; END; 
PROCEDURE ProcessRsrcs(pResType: ResType;pProcPtr: ProcPtr); END; 
FORWARD; PROCEDURE — Count Infected; 
FUNCTION RemovedRsrc(pRsrcPtr: TRsrcPtr):BOOLEAN; FORWARD; BEGIN 


PROCEDURE TraceRsrc(pStr: 517255; 
pRsrcPtr: TRsrcPtr); FORWARD; 

($S Fingerprint) 

($1 Fingerprint.ipas ) 


IF gOptionleTrace) THEN 
Trace( 'CountInfected^); 

INCCgCounts. f Infected); 

INCCgTotals.f Infected); 


($S Globals) END; 
PROCEDURE A AbortPatrolIfCmdPeriodPressed: PROCEDURE DirectoryBegins; 
BEGIN BEGIN 


WHILE GetNextEvent(gEvtMask, gEvt) DO 
WITH gEvt DO 


IF gOQptionleTrace) THEN 
Trace( ‘DirectoryBegins’ ); 


IF (what = nullEvent) THEN gReportFlags.fWroteDirname := FALSE; 
LEAVE gscreenF lags.fWroteDirname := FALSE; 
ELSE IF Cwhat = keyDown) THEN END; 
IF (BAnd(modif iers, cmdKey )=cmdKey ) R R i r 
AND CBAnd(Cmessage, charCodeMask )=$2E ) BEGIN 
THEN IF gOption[eTrace] THEN 
BEGIN Trace( ‘DirectoryEnds’); 
gAbortPatrol := TRUE; СЖ 
WryteLn( ‘Patrol aborted’); Wryte (“End of ‘); 
LEAVE; WryteLnCgCurrDirname); 
END; х) 
END; END; 
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FUNCTION Disinfected nVIR: BOOLEAN; 
VAR 
snVIR2: TRsrcRec; 
sCodeGone: BOOLEAN; 
BEGIN 
IF gOption[eTrace] THEN 
Trace( ‘Disinfected_nVIR’); 
Disinfected_nVIR := FALSE; 
InitRsrcCesnVIR2); 
GetRsrc C8snVIR2, "nVIR^,2,ResIQ); 
WITH snVIR2 DO 
BEGIN 
IF (fFlag © kRsrcHdlValid) THEN 
BEGIN 
ErrorInfected(C No nVIR 217); 
Re leaseRsrc(@gCurrRsrc); 
EXITCDisinfected_nVIR); 
END; 
IF (fSize < 8) THEN 
BEGIN 
ErrorInfected(’Too small nVIR 217); 
Re leaseRsrc(@gCurrRsrc); 
Re leaseRsrc(@snVIR2); 
EXITCDisinfected_nVIR); 
END; 
MoveHHi(fHd1); 
HLock (fHd1); 
IF NOTCFixedCode@CTUTEPtr(fHd1l*))) THEN 
BEGIN 
ReleaseRsrc(@gCurrRsrc); 
ReleaseRsrc(@snVIR2); 
EXITCDisinfected. nVIR2; 
END; 
Disinfected.nVIR := TRUE; 
sCodeGone := RemovedRsrc(@gCurrRsrc); 
ReleaseRsrc(@snVIR2); 
ProcessRsrcs( ‘nVIR’, @ProcessRemoveRsrc); 
IF sCodeGone 
AND (Count IResources( ‘nVIR’) = Ø) THEN 
ErrorMsg( ‘nVIR removed’, @) 
ELSE 
BEGIN 
ErrorMsg(‘nVIR "disinfected^:^,0); 
CommentBegins; 


Wryte (‘All of its resources are now ”); 
Wryte (“harmless, but some were not '); 


WryteLn( ‘removed, for some reason. ’); 
END; 
END; 
END; 
FUNCTION Disinfected. Scores: BOOLEAN; 
BEGIN 
IF д0рііоп[еТгасе] THEN 
Trace( ‘Disinfected_Scores’ ); 
Disinfected_Scores := FALSE; 
WITH gCurrRsrc DO 
BEGIN 
MoveHHiCfHdl2; 
HLock (fHd1); 
WITH TScoresHdlCfHd12^^ DO 
IF  NOTCFixedCodeOC8fOldJTE)) THEN 
BEGIN 
ReleaseRsrc(@gCurrRsrc); 
EXIT(Disinfected Scores); 
END; 
Disinfected_Scores := TRUE; 
IF RemovedRsrc(@gCurrRsrc) THEN 
ErrorMsg( ‘Scores removed’, ø) 
ELSE 
ErrorMsg( ‘Scores disinfected’ ,8); 
END; 
END; 
PROCEDURE ErrorBegins(pStr: Str255); 
BEGIN 
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WryteF ilename; 

Wryte (glnd); 

Wryte (glnd); 

Wryte (pStr); 

END; 

PROCEDURE ErrorEndspBeeps: INTEGER); 
VAR 


i,sBeeps: INTEGER; 
BEGIN 
IF  gOption[eBeeps] THEN 
BEGIN 
IF СрВеерѕ > 4) THEN 
sBeeps := 4 
ELSE 


sBeeps := pBeeps; 

FOR i := 1 TO sBeeps DO 
SysBeep(3); 
D . 


IF gOption[eAwait] ТНЕК 
BEGIN 
WrgteLnC^ CWAITING ON KEY PRESS)/ ); 
AwaitKeupress; 
END 
ELSE 
WruteEoln; 
END; 
PROCEDURE ErrorlInfecteXpStr: Str255); 
BEGIN 
IF NOTCgInfectedWritten) THEN 
BEGIN 
ErrorBegins(’**! INFECTED! жж *); 
WryteEoln; 
gInfectedWritten := TRUE; 
END; 
IF (pStr «> '^) THEN 
BEGIN 
CommentBegins; 
WryteCpStr); 
ErrorEnds(3); 
END; 
END; 
PROCEDURE ErrorMsg(pStr: Str255;pBeeps: 
BEGIN 
ErrorBegins(pStr); 
ErrorEnds(pBeeps); 
END; 
PROCEDURE Error0SErrtpStr: Str255); 
BEGIN 
IF (pStr © '^) THEN 
BEGIN 
ErrorBegins(pStr); 
WryteEoln; 
END; 
CommentBegins; 
Wryte (05Егг code = ”); 
WryteNbr(CgError, 1); 
ErrorEnds(2); 
END; 


FUNCTION _FixedCodeXpuTPtr: TUTEPtr): BOOLEAN; 


BEGIN 
FixedCode@ := FALSE; 
IF gQptionleTrace] THEN 
Trace( ‘FixedCode’); 
IF NOTCUTEISValidCpJTPtr)) THEN 
BEGIN 
ErroriInfected( ‘Bad Jump Table Entry! ^5; 
EXITCF ixedCode); 
END; 
IF  NOTCgOptionteRmVir1) THEN 
BEGIN 
ErrorInfected( “Remove option off’); 
CommentBegins; 
WITH pJTPtr^ DO 
BEGIN 


Wyte  C'Jumps to °); 
WruteNbr(fOffset,1); 
Wyte (“of CODE '); 
WruteNbr(fSegId,1); 
WruteEoln; 
END; 
ErrorMsg( ‘Not removed’, 1); 
EXITCFixedCode® ); 
END; 
WITH gCode? 00 
BEGIN 
IF gOption[eTrace] THEN 
BEGIN 
ТгасеС ‘About to restore CODE 0”); 
Abor tPatrolIfCmdPer iodPressed; 
IF gAbortPatrol THEN 
EXITCF ixedCode@ ); 
END; 
TJTHdlCfHdl2^^.fJTEntry( 1] := pJTPtr^; 
IF (CBAnd(fResAttrs,resProtected) © 0) 
AND CfResAttrs © -1) THEN 
BEGIN 
SetResAttrsCfHd1,0); 
ChangedResource(fHd1); 
gError := ResError; 
SetResAttrsCfHdl,fResAttrs); 
END 
ELSE 
BEGIN 
ChangedResource(fHd1); 
gError := ResError; 
END; 
IF СдЕггог © NoErr) THEN 
BEGIN 
ErrorInfected( ‘CODE 0 unchanged! ^); 
IF (CgError = wPrErr) THEN 
ErrorMsg( ‘Disk is locked’ ,9) 
ELSE 
ErrorOSErr¢’’); 
gError := 9; 
EXITCF ixedCode£); 
END; 
WriteResource(fHd1); 
gError := ResError; 
IF (gError © NoErr) THEN 
BEGIN 
ErrorInfectedC ‘CODE Ø unwritten! ^); 
ErrorOSErr(' ^); 


EXITCF ixedCode£); 
END; 
END; 
FixedCode® :- TRUE; 
END; 


R 
(pRsrcPtr: TRsrcPtr; 
pResType: ResType; 


pInt: INTEGER; 
pIntIs: TResIdOr Index); 
VAR 

sName : 547255; 
sResLoad: BOOLEAN; 

Whi 
BEGIN 
CommentBegins; 
WryteTypeCpResType); 


WryteChar(’ '); 
WryteNbr CpInt, 15; 
IF (plntIs = Index) THEN 
Wryte (” Cindexed)’); 
WryteEoln; 
END; 
BEGIN 
WITH pRsrcPtr^ DO 
BEGIN 
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IF (fFlag © kRsrcIsInitd) THEN 
BEGIN 
ErrorMsg( ‘Logic error using GetRsrc’,4); 
AwaitKeypress; 
ExitSecurityPatrol; 
fResType := pResType; 
fResId := pint; 
sResLoad := (TWordPtr(kResLoad)* ‹ 0); 
IF (gActiveSelf OR gActiveSys) THEN 


Se tResLoad (FALSE); 
IF (plntIs = Index) THEN 
BEGIN 


IF gOption[eTrace] THEN 
TraceRsrc( ‘About to get ind’,pRsrcPtr); 
fHdl := Get i1IndResource(pResType, pInt); 
END 
ELSE 
BEGIN 
IF gQptionleTrace] THEN 
TraceRsrc( ‘About to get’,pRsrcPtr); 
fHdl := Get IResourceCpResType,pInt); 
END; 
IF sResLoad THEN 
BEGIN 
IF (CgActiveSelf OR gActiveSys) THEN 
Se tResLoad (TRUE); 
IF (fHd] = NIL) 
OR CORD4CfHd1) = -1) THEN 
BEGIN 
gError := ResError; 
ErrorOSErr(’Couldn’t get resource’); 
CommentWhich; 
InitRsrc(pRsrcPtr); 
EXITCGetRsrc); 
END; 
fFlag := kRsrcHdlValid; 
fResAttrs := GetResAttrsCfHd15; 
IF (ResError © NoErr) THEN 
fResAttrs := -1; 
IF  CfHdl^ = NIL) THEN 
BEGIN 
LoadResource(fHd1); 
fLoaded := eWeLoadedIt; 
IF  gOption[eTrace] THEN 
TraceC'We loaded it’); 
END 
ELSE 
BEGIN 
fLoaded := eAlreadyLoaded; 
IF gOption[eTrace] THEN 
TraceC'Already loaded’); 


END; 
IF СЕНТ“ = NIL) THEN 
BEGIN 
gError := ResError; 
IF (gError € NoErr) THEN 
BEGIN 
ErrorMsg( ‘Couldn’t load resource’ ,@); 
IF (CgError = memFullErr) THEN 
ErrorMsg(‘No room in heap zone’, 1) 
ELSE 
Еггог05Егг(””); 
CommentWhich; 
ReleaseRsrc(pRsrcP tr); 
EXITCGetRsrc); 
END; 
END; 
fSize := SizeResource(fHdl); 
END 
ELSE 
BEGIN 
fFlag := kRsrcHdlValid; 
fSize := MaxSizeRsrcCfHd1); 
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fLoaded := eNotYet; 
IF gOption[eTrace] THEN 
TraceC'No-load get, loaded not yet’); 
END; 
IF (pIntIs = Index) THEN 
BEGIN 
GetResInfoCfHdl, fResId, fResType, sName); 
gError := ResError; 
IF СдЕггог © NoErr) THEN 
BEGIN 
ErrorOSErrC'Couldn^t get resource id’); 
CommentWhich; 
ReleaseRsrc(pRsrcPtr); 
EXITCGetRsrc); 
END; 
END; 
IF  sResLoad THEN 
BEGIN 
fState := HGetState(fHdl); 
IF CCfResType = ‘CODE’) 
AND (fResId = 0)) THEN 
BEGIN 
MoveHHi CfHd1); 
HLock (fHd1); 
END 
ELSE 
HNoPurge(fHd1); 
END; 
END; 
IF gOptionleTrace] THEN 
TraceRsrc( ‘Got’, pRsrcPtr); 
INCCgCounts.fResources); 
INCCgTotals .f Resources); 
END; 
PROCEDURE — InitGlobals; 
VAR 
sGetHd],sPutHd]: ^| DialogTHndl; 
sGetSize,sPutSize,sScrnSize: Point; 
BEGIN 
Zero0utRange(@gAAGlobals, @gZZG1obals); 
gCurrl0Buffer := NewPtr(kIOBufferSize); 
InitRsrcCégCode0); 
InitRsrcCégCurrRsrc); 
gEvtMask := 
everyEvent - CupdateMask + activMask); 
GetPort(gGrafPtr); 
gInd = f б 
SGetHdl := DialogTHndlCGetResource( 0106” ,getD1gID22; 
IF (sGetHdl = NIL) 
OR (LONGINTCsGetHdl) = -1) THEN 
SetPt(sGetSize,304,104) 
ELSE 
BEGIN 
IF (sGetHdl^ = NIL) THEN 
LoadResource(Handle(sGetHd1)); 
sGetSize := sGetHdl1**.boundsRect.botRight; 
Re leaseResource(Handle(sGetHdl )); 
END; 


sPutHd] := DialogTHnd1(GetResource( ‘DLOG’, putD1gID)); 


IF  (sPutHdl = NIL) 

OR CLONGINTCsPutHd]) = -1) THEN 
SetPt(sPutSize, 348, 136) 

ELSE 
BEGIN 
IF (CsPutHdl^ = NIL) THEN 

LoadResource(Handle(sPutHd1 )); 

sPutSize := sPutHd]**.boundsRect .botRight; 
Re leaseResource(Handle(sPutHd1 )); 


END; 

WITH gGrafPtr*.portBits.bounds DO 
BEGIN 
sScrnSize.h := right-left; 
sSernSize.v := bottom-top; 
END; 
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gSFGetPt.h := CsScrnSize.h-sGetSize.h) DIV 2; 
gSFGetPt.v := (sScrnSize.v-sGetSize.v) DIV 2; 
gSFPutPt.h := (sScrnSize.h-sPutSize.h) DIV 2; 
gSFPutPt.v := CsScrnSize.v-sPutSize.v) DIV 2; 
END; 


PROCEDURE InitRsre (pRsrcPtr: TRsrcPtr); 
BEGIN 
ZeroOut(Ptr(pRsrcPtr ), SIZEOFCTRsrcRec)); 
pRsrcPtr^.fFlag := kRsrcIsInitd; 
END; 
FUNCTION — JTEIsValid CpJTEPtr: TJTEPtr2: BOOLEAN; 
VAR 
sCode: TRsrcRec; 
BEGIN 
IF gOptionteTrace] THEN 
Trace( ‘JTEIsValid’); 
JTEIsValid := FALSE; 
WITH pJTEPtr^, sCode DO 
BEGIN 
InitRsrc(@sCode); 
Se tResLoad(FALSE); 
GetRsrc(@sCode, ’CODE’, fSegId, ResId); 
Se tResLoad( TRUE); 
IF (fFlag O kRsrcHdlValid) THEN 
EXITCUTEIsValid); 
JTEIsValid := 
(fSkip3F3C = $3F3C) AND 
(fSegId > 0) AND 
(fSkipA9FØ = -22032) AND ( $A9FØ ) 
(fSize › 0); 
ReleaseRsrc(@sCode); 
END; 
END; 
PROCEDURE ListCountspPtr: TCountsPtr); 
BEGIN 
IF gOptionleTrace] THEN 
Тгасе( ‘CountsListing’); 
WITH pPtr* DO 
BEGIN 
WryteLn ( ‘Files: /); 
WryteNbr(CfFiles, 6); 
WryteLn (° processed’); 
WryteNbr (fExamined, 6); 
WryteLn (° examined’); 
WryteNbr(fDeleted, 6); 
WryteLn (' deleted’); 
WryteLn C'Resources: ^); 
WryteNbr(fResources, 6); 
WryteLn (° processed’); 
WryteNbr(f Infected, 6); 
WryteLn (° infected’); 
WryteNbr(fRemoved, 6); 
WryteLn C' removed’); 
Wryte (‘Currently available memory is '); 
WryteNbr(MemAvail DIV 1024, 1); 
WryteLn ('K.7); 
PauseBr ief ly; 
END; 
END; 
R Fork 
VAR 
sWeUsedToBeInfected: BOOLEAN; 
PROCEDURE GetistCode: 
BEGIN 
WITH TUTHd1(gCode®.fHd1)**.fuTEntryl1] DO 
BEGIN 
GetRsrc(@gCurrRsrc, CODE’, fSegId,ResId); 
IF (gCurrRsrc.fFlag<>kRsrcHd1Valid) THEN 
BEGIN 
ErrorInfectedC'Couldn^t get ist CODE’); 
InitRsrc(@gCurrRsrc); 
EXITCLookForKnownViruses); 
END; 
END; 
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END; 
BEGIN 
IF gOption[eTrace] THEN 
Trace('"LookForKnownViruses'); 
sWeUsedToBeInfected := FALSE; 
GetlstCode; 
WITH gCurrRsrc DO 
BEGIN 
LookForVirus_nVIR; 
IF fiInfected THEN 
BEGIN 
Count Infected; 
IF fKnown AND (fSize = 372) THEN 
ErrorInfectedC'nVIR 372 virus’) 
ELSE IF fKnown AND CfSize = 422) THEN 
ErrorInfected(‘nVIR 422 virus’) 
ELSE 
BEGIN 
ErrorInfected( ‘New nVIR virus! ^); 
gFgPrTitle := °’; 
CommentFgPrRsrc(@gCurrRsrc); 


IF Disinfected_nVIR THEN 
sWeUsedToBeInfected := TRUE; 
Get istCode; 
END; 
LookForVirus_Scores; 
IF fKnown AND fInfected THEN 
BEGIN 
Count Infected; 
ErrorInfected( ‘Scores virus’); 
IF Disinfected_Scores THEN 
sWeUsedToBeInfected := TRUE; 
END 
ELSE 
ReleaseRsrc(@gCurrRsrc); 


END; 
IF sWeUsedToBeInfected THEN 
LookForKnownV iruses; 
END; 


BEGIN 
IF gOption[eTrece] THEN 
Trace( ‘PatrolBegins’ ); 
WryteEoln; 
Wrytel nC EX XXX EXXXrXrr*rrrzrirrrfrrrirri) 
ZeroOutCegCounts, SIZEOF CTCountsRec)); 
GetDateT ime(gSecsBegins); 
END; 


VAR 
sMins, sSecs: INTEGER; 
BEGIN 
GetDateT imeCgSecsEnds); 
sSecs := gSecsEnds - gSecsBegins; 
sMins := sSecs DIV 60; 


sSecs := sSecs - (sMins * 60); 

WryteEoln; 

WryteLnC ^EXXEEEEEEEEREXXZEEXZXTYXXEXYXEXE!) 
WryteEoln; 


Wryte (“End of patrol that took '); 
WryteNbr(CsMins, 1); 
WryteChar(‘: 7); 
IF (sSecs < 10) THEN 
BEGIN 
WryteChar (‘8’); 
WryteNbr (sSecs, 1); 
END 
ELSE 
WryteNbr (sSecs,2); 
WryteEoIn; 
ListCounts(@gCounts ); 
END; 
PROCEDURE PauseBrief ly; 
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VAR 

sTicks: LONGINT; 
BEGIN 
Delau(120,sTicks); 
END; 


VAR 
i,sNbrEntries,sPrevId: INTEGER; 
sWeirdCode0: BOOLEAN; 
R 
BEGIN 
CommentBegins; 
Wrute (“At entry °); 
WruteNbr(i,1); 
WryteEoln; 
END; 
BEGIN 
IF gOptionfeTrace] THEN 
Тгасе( 'ProcessCodes ^); 
GetRsrc(@gCoded, ‘CODE’, 0, ResId); 
IF (gCode®.fFlag € kRsrcHdlValid) THEN 
BEGIN 
ErrorMsgC'Code rsrcs without CODE 9’, 1); 
EXITCProcessCodes); 


END; 
IF NOTCCode@IsValid) THEN 
BEGIN 
ErrorMsg( ‘Unexpected CODE 0 values’, 1); 
Re leaseRsrc(@gCoded ); 


EXITCProcessCodes); 
END; 
LookForKnownV iruses; 
WITH TJTHdlCgCode2 .fHd1)^* 00 
BEGIN 
sNbrEntries := fNbrBytesInTable DIV 8; 
sPrevId = 1; 
sWeirdCode® := 


CCOPYCgCurrF i lename, 1,9)=’Red Ryder’) OR 

(COPYCgCurrFilename, 1,6)=’Canvas’ >) OR 

CCOPYCgCurrF i lename, 1,9)=’PageMaker ’ ); 
FOR i := 1 TO sNbrEntries DO 

WITH fJTEntryLi] DO 


BEGIN 

IF (fSkip3F3C = $3F3C) 

AND CfSegId = sPrevId) 

AND (fSkipA9F@ = -22032) THEN 
CYCLE; 


Abor tPatrolIfCmdPer iodPressed; 
IF gAbortPatrol THEN 


LEAVE; 
IF NOTCJTEIsValidCef JTEntryL i12) THEN 
BEGIN 
ErrorMsg(‘CODE 0 has invalid JTE’, 1); 
CommentWhere; 
LEAVE; 
END; 
IF sWeirdCode® THEN 
BEGIN 
sPrevId := fSegld; 
CYCLE; 
END; 
IF (fSegId < sPrevId) THEN 
BEGIN 
ErrorMsgC^JT not ascending’, 1); 
CommentWhere; 
LEAVE; 
END; 
INCCsPrevId); 
IF (fSegId = sPrevId) THEN 
CYCLE; 
ErrorMsgC'JT skips ResId’, 1); 
CommentWhere; 
LEAVE; 
END; 
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END; 
ReleaseRsrcCegCode2); 


END; 
PROCEDURE  ProcessFile; 
VAR 
sSaveC iT: INTEGER; 
BEGIN 
IF (gError © NoErr) THEN 
BEGIN 


IF CgError = eofErr) THEN 
( no resource fork } 
ELSE IF (gError = fnfErr) THEN 
ErrorMsg( ‘File not found’, 1) 
ELSE IF (gError = nsvErr) THEN 
ErrorMsg(‘No such volume’, 1) 
ELSE IF (gError = opWrErr) THEN 
ErrorMsg(CONCATC ‘Already in use. ”, 
‘(Don’t use under MultiFinder!)’), 1) 
ELSE 
ErrorOSErr(C'Couldn't open file’); 
gError := NoErr; 
EXITCProcessF ile); 
END; 
END; 
BEGIN 
IF gOptionleTrace] THEN 
Trace( ‘ProcessFile’); 
Abor tPatrolIfCmdPer iodPressed; 
IF gAbortPatro] THEN 
EXITCProcessF ile); 
INCCgCounts . fF iles); 
INCCgTotals .fFiles); 


gInfected :* FALSE; 
gInfectedWritten :* FALSE; 
gReportFlags.fWroteFilename := FALSE; 
gScreenF lags.fWroteFilename := FALSE; 


IF gOption[eLList] THEN 
WryteF i lename 
ELSE 
WryteF ilenameToScreenOnlyForNow; 
IF CLENGTHCgCurrFilename) > Ø) THEN 
IF CgCurrFilename(1] = ‘.’) THEN 
BEGIN 
ErrorMsg( ‘Filename begins with *.”’, 1); 
EXITCProcessF ile); 
END; 
IF gActiveSelf AND NOT(kProcessSelf) THEN 
EXITCProcessF ile); 
gCurrEOF := -1; 
gError := FSOpenCgCurrF ilename, gCurrWDRefNum, gCurrRefNum); 
ExitIfCantReadFork; 
gError := GetEOFCgCurrRefNum, gCurrEOF 5; 
IF (gError = NoErr) THEN 
BEGIN 
WITH gCurrFInfo DO 
IF CCOPYCgCurrFilename, 1,722" MacsBug ^) 
OR (fdType = 'RELB^) 
OR (fdType = “OBJ ') THEN 
IF NOTCKnownDataFork) THEN 
CommentFgPrData; 
gError := FSCloseCgCurrRefNum); 
IF (gError € NoErr) THEN 
ErrorOSErrC^Couldn^t close data fork’); 
END 
ELSE 
ErrorOSErrC'Couldn^t GetEOF '); 
IF gActiveSelf THEN 


BEGIN 
gCurrRefNum := TWordPtr(kCurApRefNum)°; 
gError :- NoErr; 
END 
ELSE IF gActiveSys THEN 
BEGIN 
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gCurrRefNum := TWordPtr(kSysMap)°*; 
gError :- NoErr; 


BEGIN 
Se tResLoad(FALSE); 
gCurrRefNum := OpenRFPerm(gCurrF i lename, gCurr WDRef Num, 
fsRdWrPerm); 
gError :- ResError; 
Se tResLoad( TRUE); 
ExitI fCantReadFork; 
END; 
IF (gCurrRefNum <> CurResFile) THEN 
BEGIN 
UseResF i leCgCurrRef Num); 
gError := ResError; 
IF  €gError «€ NoErr) THEN 
BEGIN 
ErrorOSErrC'Couldn'/t use resource fork’); 
gError := NoErr; 
EXITCProcessF ile); 
END; 
END; 
INCCgCounts . fExam ined); 
INCCgTotals .fExamined); 
IF (Count iResources(‘CODE’) > Ø) THEN 
ProcessCodes; 
gFgPrTitle := “Unknown Resource(s): ’; 
ProcessRsrcs( ‘ADBS’ , @Process_ADBS); 
ProcessRsrcs( ‘CACH’, ӨРгосеѕѕ_САСН); 
ProcessRsrcs( ‘CDEF ^, @Process_CDEF); 
(etc) 
IF gOption[eFgPr] THEN 
BEGIN 


gFgPrTitle := ‘Fingerprint(s): ’; 
ProcessRsrcs( ‘ADBS’, 6ProcessCurrRsrc); 
ProcessRsrcs( ‘CACH’, @ProcessCurrRsrc); 
ProcessRsrcs( ‘CDEF ’, @ProcessCurrRsrc); 
IF gOption[eFgPrC] THEN 
ProcessRsrcs¢ ‘CODE’, @ProcessCurrRsrc); 

ProcessRsrcs( ‘DATA’, @ProcessCurrRsrc); 
(etc) 
ProcessRsrcs¢ ‘nVIR’, 6ProcessCurrRsrc); 
END; 

IF gActiveSelf OR gActiveSys THEN 
EXITCProcessF ile); 

sSaveC iT := Count 1Туреѕ; 

CloseResF i leCgCurrRef Num); 

IF NOTCgInfected) THEN 
EXITCProcessF ile); 

WITH gCurrFInfo DO 
BEGIN 
IF €€gCurrFilename = ‘Note Pad File’) 
OR (gCurrFilename = ‘Scrapbook File’)) 
AND (fdCreator = ‘ZSYS’) 
AND gOptionleRmVir] THEN 


BEGIN 

fdType := '7SYS'; 

fdCreator := ‘MACS’; 

fdFlags := 4096; 

gError := SetFInfoCgCurrFilename, 
gCurrWDRefNum, 
gCurrF Info); 


IF (gError = NoErr) THEN 
ErrorMsg( ‘Reset to system document’ ,0) 
ELSE 
ErrorOSErrC'FInfo not reset’); 
EXITCProcessFile); 
END; 
END; 
IF (gCurrEOF <> Ø) THEN 
BEGIN 
ErrorMsg( ‘File still has data fork’,@); 
ErrorMsg( ‘File not deleted’, 1); 
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EXIT(ProcessFile); TraceRsrcC'About to release’,pRsrcPtr ); 


END; IF (gActiveSelf OR gActiveSys) THEN 
IF (sSaveCiT ‹ 0) THEN IF gOption[eTrace] THEN 

BEGIN Trace( ‘Not Released’) 

ErrorMsg( ‘File still has resources’ ,9); ELSE 

ErrorMsg( ‘File not deleted’, 1); ELSE 

EXITCProcessF ile); BEGIN 

END; HSetStateCfHdl, fState); 


ErrorMsg( ‘File emptied’ ,9); 


Re leaseResource(fHd1); 
gError := FSDeleteCgCurrF i lename, gCurrWDRef Num); 


IF gOption[eTrace] THEN 


IF (gError = NoErr) THEN Trace( ‘Released’ ); 
BEGIN | END; 
gCurrF ileDeleted := TRUE; InitRsrc(pRsrcP tr); 
INCCgCounts.fDeleted); END; 
INCCgTotals.fDeleted); END; 
ErrorMsg( ‘File deleted’, 1); FUNCTION — RemovedRsre(pRsrcPtr: TRsrcPtr): BOOLEAN; 
END VAR 
ELSE sBitsQandT :LONGINT; 
ErrorOSErr( ‘File not deleted’); PROCEDURE  ExitIfError(pStr: $tr255); 
END; BEGIN 
PROCEDURE ProcessRsrcXpResType:ResType; pProcPtr: ProcPtr); gError := ResError; 
VAR IF (CgError «€» NoErr) THEN 
i,sIdx: INTEGER; BEGIN 
BEGIN ErrorMsg(pStr,2); 
IF  gOptionteTrace] THEN IF (CgError = wPrErr) THEN 


Trace ‘ProcessRsrcs’ ); 

WITH gCurrRsrc DO 

BEGIN 

sIdx := 1; 

FOR i := 1 TO Count iResources(pResType) 00 
BEGIN 


ErrorMsg( ‘Disk is locked’ ,@) 
ELSE 

Еггог05Егг(””); 
CommentRsrcBegins(pRsrcPtr); 
WryteLn(‘ not removed’); 
Re leaseRsrc(pRsrcPtr); 


AbortPatrolIf CndPer iodPressed; EXITCRemovedRsrc); 
IF gAbortPatrol THEN END; 

LEAVE; END; 
GetRsrc(@gCurrRsrc, pResType, sIdx, Index); BEGIN 


IF (fFlag < kRsrcHdlValid) THEN 
BEGIN 


RemovedRsrc := FALSE; 
IF gQptionleTrace] THEN 


INCCsIdx); Trace( ‘RemovedRsrc’ ); 
CYCLE; Abor tPatrolIfCmdPer iodPressed; 
END; IF gAbortPatro] 


Са11РгосРігСрРгосРїг); 


OR NOT(gOption[eRmVir]) THEN 


IF flnfected THEN BEGIN 
BEGIN ReleaseRsrc(pRsrcPtr); 
CountInfected; EXIT(RemovedRsrc); 
ErrorInfected(’ ^); END; 
CommentRsrcBegins(@gCurrRsrc); WITH pRsrcPtr^ DO 
WryteLn(’ is an infection’); BEGIN 


IF RemovedRsrc(@gCurrRsrc) THEN 
BEGIN 


IF (fFlag € kRsrcHdiValid) THEN 
BEGIN 


ErrorMsg( ‘Removed’ , 8); ErrorMsg( ‘Error using RemovedRsrc’ ,4); 
CYCLE; Awai tKeypress; 
END; ExitSecurityPatrol; 

ErrorMsg( ‘Not removed’, 1); END; 

INCCsIdx); IF gQptionleTrace] THEN 

CYCLE; BEGIN 

END; TraceRsrc( ‘About to remove’,pRsrcPtr); 


IF NOTCfKnown) THEN 
CommentFgPrRsrc(@gCurrRsrc); 
ReleaseRsrc(@gCurrRsrc); 


Abor tPatrolIfCmdPer iodPressed; 
IF gAbortPatrol THEN 
EXITCRemovedRsrc); 


INC(SIdx); END; 
END; IF NOTCfInfected) THEN 
END; BEGIN 
END; ErrorMsg( ‘Tried to remove uninfected',4); 
PROCEDURE  ReleaseRsrc(pRsrcPtr: TRsrcPtr); AwaitKeypress,; 
BEGIN ExitSecurityPatrol; 
WITH pRsrcPtr^ DO END; 
BEGIN IF kZeroOutVirs AND CfHdl^ <> NIL) THEN 
IF CfFlag © kRsrcHdlValid) THEN BEGIN 
BEGIN ZeroOut(fHdl*, fSize); 
ErrorMsg( ‘Error using ReleaseRsrc’,4); ChangedResourceCfHd1); 
AwaitKeypress; gError := ResError; 
ExitSecurityPatrol; IF (gError = NoErr) THEN 
END; BEGIN 


IF gôptionleTrace] THEN WriteResource(fHd1): 
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gError := ResError; 
IF (gError <> NoErr) THEN 
ErrorOSErrC'Couldn^t WriteResource’ ); 


END 
ELSE 
Еггог05Егг( ‘Couldn’t ChangedResource’ ); 
END; 
5Віёѕдапат :- BAnd(fResAttrs, $81); 


SetResAttrs(fHdl, LoWord(sBits@and7)); 
RmveResource( fHd1); 
ExitIfErrorC'Couldn't remove resource’); 
UpdateResF i leCgCurrRefNum); 
ExitIfErrorC'Couldn^t update res file’); 
DisposHandleCfHdl); 
InitRsrcCpRsrcPtr); 
RemovedRsrc := TRUE; 
IF gOptionfeTrace] THEN 
TraceC'RemovedRsrc successful’); 
END; 
INCCgCounts. fRemoved); 
INCCgTotals.fRemoved); 


END; 
R rtH 
(pPtr: Ptr; 
pNbrBytes: SignedByte); 
VAR 
i: INTEGER; 
sChl,sCh2,sDigit: LONGINT; 
sIdx: Ptr; 
BEGIN 
SIdx := pPtr; 
FOR i := 1 TO pNbrBytes 00 
BEGIN 
sDigit := ORD4(sIdx*); 
SCh1 :- BSRCBAnd(sDigit,$F@),4); 
sCh2 = BAnd(sDigit, $0F); 


IF sChi > 9 THEN 
WryteCharCCHRCsCh1 + $37)) 
ELSE 
WryteCharCCHRCsCh1 + $3055; 
IF sCh2 > 9 THEN 
WryteCharCCHRCsCh2 + $37)) 
ELSE 
WryteCharCCHRCsCh2 + $305); 
INCCLONGINTCsIdx2); 
END; 
END; 
PROCEDURE  Trace(pStr: 
BEGIN 
ErrorBegins(pStr); 
ErrorEnds(@); 
END; 
PROCEDURE TraceNbr(pStr: 
BEGIN 
ErrorBegins(pStr); 
WruteNbr(pNbr,1); 
ErrorEnds(0); 
END; 
PROCEDURE TraceRsrcpStr: Str255;pRsrcPtr: 
BEGIN 
ErrorBegins(pStr ); 
WITH pRsrcPtr^ DO 
BEGIN 
WryteCharC' '); 
WryteType(fResType); 
WryteNbr (fResId,7); 
END; 
ErrorEnds(@); 
END; 
PROCEDURE ZeroOut(pStart: 
VAR 
i: INTEGER; 
sIdx: Ptr; 
BEGIN 


Str255); 


9tr255; pNbr : 
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Ptr;pCount: Size); 


LONGINT2; 


TRsrcPtr); 


sIdx := pStart; 
FOR i := 1 TO pCount DO 


BEGIN 
sIdx^ := 0; 
INCCLONGINT(sIdx)); 
END; 
END; 
PROCEDURE  ZeroOutRang&pl1: Ptr; p2: Ptr); 
VAR 
i: INTEGER; 
sIdx: Ptr; 
BEGIN 
IF (0804(р12 < ORD4(p2)) THEN 
SIdx := pl 
ELSE 
SIdx := p2; 


FOR i := 1 TO ABSCORD4(p2)-ORD4(p1))+1 DO 
BEGIN 
sIdx^ := 0; 
INCCLONGINT(sIdx)); 
END; 
END; 
END. 


“MainDlog.p” 
UNIT MainDlog; 
INTERFACE 
USES 


MemTypes, QuickDraw,OSIntf,ToolIntf, PackIntf,Globals; 


PROCEDURE InitMainDlog; 


FUNCTION — MainDlogWorkRequested:  TMainItem; 
IMPLEMENTATION 
($R-) 
CONST 
(——item range——) 
kI temFst = eDirs; 
kItemLst = eDBtn; 
(—item type subranges-) 
kBtnFst - eDirs; 
kBtnLst = eQuit; 
kChkFst = eAwait; 
kChkLst - eTrace; 
kStatFst - eMain; 
kStatLst = eScOW; 
kUItmFst - eDBtn; 
kUItmLst - eDBtn; 
(-titled item subrange-) 
kTItmFst = eDirs; 
kTItmLst = eScOW; 
TYPE 
TDitmPtr - ^TDitmRec; 
TDitmRec = 
PACKED RECORD 
fProcPtr: ProcPtr; 
fRect: Rect; 
f Type: Byte; 
fLen: Byte; 
fData: INTEGER; 
END; 
VAR 
gDBtnRect: Rect; 
gHd1: ARRAY [eAwait..eTrace] 
OF ControlHandle; 
gRect: ARRAY [eAwait..eTrace] 
OF Rect; 
PROCEDURE ChkChk(pItem: — TMainItem); 


BEGIN 
IF (pItem < kChkFst) 
OR (pltem > kChkLst) THEN 
BEGIN 
sysBeep(3); 
EXITCChkChk ); 
END; 
SetCt]Value(gHd1 [pI tem], ORDCgOpt ion[pItem12); 
IF gDisabled[pItem] THEN 


BEGIN 
SetDItem(gDl1ogPtr,ORD(pltem), 
ctriltemtchkCtr1+itemDisable, 
HandleCgHdl [pI tem]),gRect[pI tem] ); 
HiliteControlCgHdl [pI tem], 255); 
END 
ELSE 
BEGIN 
SetDItemCgDlogPtr , ORD(pI tem), 
ctrlItem*chkCtr], 
HandleCgHdl [pItem]),gRect [pItem]12; 
HiliteControlCgHdlIpItem1,2); 
END; 
END; 


pWindowPtr:WindowPtr; pItemNo: 


INTEGER); 
VAR 
sPenState: PenState; 
BEGIN 
GetPenStateCsPenState); 
PenSize (3,3); 
FrameRoundRect(gDBtnRect, 16, 16); 
SetPenState(sPenState); 


END; 
R itMai 
CONST 
kTitleMax = 21; 
kTItmLen - 42; 
( 14 + kTitleMax + ordCodd(kTitleMax)); ) 
kUItmLen = 14; 
VAR 
1: TMainItem; 
sDitmPtr: TDitmPtr; 
sDlogRect: Rect; 
sHdl : Handle; 
sNorTItns: INTEGER; 
sNbrUI tms: INTEGER; 
sRect: ARRAY (eDirs..eScOW) 
OF Rect; 
sSize: Size; 
sTitle: ARRAY (eDirs..eScOW] 
OF STRINGIkTitleMax]; 
sType: INTEGER; 
BEGIN 


IF gOptionfteTrace] THEN 
TraceC' InitMainDlog'); 
FOR i := kTItmFst TO kTItmLst DO 
IF (і >= kBtnFst) 
AND Ci <= kBtnLst?) THEN 
BEGIN 
SetRect — (sRect[i], 266, 65, 346, 83); 
OffsetRect(sRect(i1,0, 27*CORDCi)-ORD(KBtnFst))); 
END 
ELSE IF Ci >= kChkFst) 
AND Ci <= kChkLst) THEN 
BEGIN 
SetRect C(sRect[i), 24, 62, 185, 80); 
OffsetRect(sRect(i1,0, 20*CORDCi)-ORDCKChkFst))); 
END 
ELSE 
SetRect (sRectlil, 12, 42, 216, 60); 
Of fsetRect(sRectleMain], 080,-30); 
OffsetRect(sRectleOpts], 000,000); 
OffsetRectCsRect[eScOW], 216,000); 
gDBtnRect := sRect[kItemFst]; 
InsetRect CgDBtnRect, -4, -4); 
WITH sDlogRect, gSFGetPt DO 


BEGIN 
top := v - 10; 
left := h- 10; 
bottom := top + 210; 
right := left + 368; 
END; 
sTitleteDirs] := ‘Directories’; 
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sTitleleDiry] := ‘Directory’; 
sTitlefeEvery] := ‘Everything’; 
sTitleleFiles] := ‘Files’; 
sTitlefeQuit] := ‘Quit’; 
sTitleleAwait] := ‘Await Keypress’; 
sTitleleBeeps] := ‘Beep’; 
sTitleleFgPr]) := ‘Fingerprint’; 
sTitleleFgPrC] := ‘Fingerprint CODES’; 
sTitlefeLList] := ‘Long Listing’; 
sTitleleRmVir] := ‘Remove Viruses’; 
sTitleleTrace] := ‘Trace’; 
sTitleleMain] := 


‘Security Patrol Main Dialog’; 
sTitlel[eOpts] := ‘Options: ’; 
sTitleleScOW] := ‘Scope Of Work: °; 
sNbrTItms := CORDCKTItmLst)-ORDCKTItmFst22* 1; 
sNbrUItms := CORDCKUI tmLst )-ORDCKUI tmFst))+1; 
sHdl :- NewHandle(2 + CsNorTItms*kTItmLen) + 
CsNbrUI tms*kUI tmLen)); 
TWordPtr(sHdl^)^ := ORDCkItemLst) - 1; 


sSize := 2; 
FOR i := kItemFst TO kItemLst DO 
BEGIN 


IF gOptionfeTrace] THEN 
TraceNbr('sSize = ‘,sSize); 
sDitmPtr := POINTERCORD4(sHd1*)+sSize); 
WITH sDitmPtr^ DO 
IF Ci >= kTItmFst) 
AND Ci <= kTItmLst) THEN 


BEGIN 
fProcPtr := NIL; 
fRect ‘= sRect[i); 


IF (i <= kBtnLst) THEN 
{Туре := ctrlItem + btnCtr]1 
ELSE IF (i <= kChkLst) THEN 
{Туре := ctrlItem + chkCtr1] 
ELSE 
{Туре := statText + itemDisable; 
BlockMove(@sTitleli],@fLen, 
LENGTH(sTitlelil)+1); 
sSize := sSize*14*fLen*ORDCODDCfLen22; 


END 

ELSE IF (Ci = eDBtn) THEN 
BEGIN 
fProcPtr := @FrameDefaultBtn; 
fRect := gDBtnRect; 
f Type := userItem + itemDisable, 
flen ‚= 0; 
sSize ‚= sSize + 14; 
END 

ELSE 
SusBeep(60); 


END; 
SetHandleSize(sHdl,sSize); 
gDlogPtr := NewDialog(NIL, sDlogRect, ^^, 
FALSE, dBoxProc, POINTERC-1),FALSE,8,SHd1); 
FOR i := kChkFst TO kChkLst DO 
BEGIN 
GetDItemCgDlogPtr,ORDCi),sType, 
HandleCgHdl[i3)2,gRect[i 12; 
IF gOption[eTrace] THEN 
TraceNbrC'ChkChk^ing item “,ORD(i)); 
ChkChk( i2; 
END; 
END; 
FUNCTION — KubdEquivsFilter(pDialogPtr: DialogPtr; 


VAR pEventRec: EventRecord;VAR pItemHit: INTEGER): BOOLEAN; 


VAR 
sChar : 
RECORD 
CASE INTEGER OF 
0:(Ғ1,Ғ2,Ғ3: SignedByte; 
Enum: TMainI tem); 
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1: (L: LONGINT); 
END; 
sltem: TMainI tem; 
BEGIN 
sItem :- eNotADlog! tem; 
WITH pEventRec DO 
IF (what = keyDown) THEN 
BEGIN 
SChar.L := BAnd(message, charCodeMask); 
IF (sChar.L = $03) 
OR CsChar.L = $00) THEN 
sItem := eDirs 
ELSE IF CsChar.L = ORD( “D )) 
OR CsChar.L = ORDC'd^)) THEN 
SItem := eDiry 
ELSE IF (sChar.L = ORDC‘E’)) 
OR (sChar.L = ORDC'e^)) THEN 
sItem := eEvery 
ELSE IF CsChar.L = 
OR (sChar.L = 
sItem := eFiles 
ELSE IF CsChar.L = ORDC‘Q’)) 
OR (sChar.L = ORDC'q^5) 
OR CCBAndCmodif iers,cmdKey) 0) 
AND CsChar.L = ORDC’.’))) THEN 
sItem := eQuit 
ELSE 
BEGIN 
sChar.L := 
CsChar .L-0RD4C^1^)) + ORDCKChkFst); 
IF (sChar.L >= ORDCkChkFst)) 
AND (sChar.L <= ORDCkChkLst)) THEN 
IF  NOTCgDisabled([sChar.Enum]) THEN 
sItem := sChar.Enum; 
END; 
END; 
IF (sItem = eNotADlogItem) THEN 
KgbdEquivsFilter := FALSE 
ELSE 
BEGIN 
pItemHit 
KybdEquivsF ilter 
END; 
END; 
FUNCTION — MainDlogWorkRequested TMainItem; 
VAR 
sItem: 
RECORD 
CASE INTEGER OF 
Q:CFiller: SignedByte; 
Enum:  TMainItem); 
1:CInt: INTEGER); 
END; 
BEGIN 
IF gOption[eTrace)] THEN 
Тгасе( ‘MainDlogWorkRequested’); 
Br ingToFrontCgDlogPtr); 
ShowWindow (gDlogPtr); 
ModalDialog C@KybdEquivsFilter,sItem. Int); 
WHILE CsItem.Enum >= kChkFst) 
AND (sItem.Enum <= kChkLst) DO 
BEGIN 
gOption[sItem.Enum] := 
NOTCgOption[sI tem.Enum]); 
ChkChk(sI tem.Enum); 
IF (CsItem.Enum = eFgPr) THEN 


ORDC'F^)) 
ORDC'f^)) THEN 
0 


ORDCsItem); 
TRUE ; 


BEGIN 
gDisabledleFgPrC] := NOTCgOptionteFgPr 12; 
gOption [eFgPrC] := FALSE; 
ChkChk CeFgPrC); 
END; 
ModalDialog (@KybdEquivsFilter,sItem. Int); 
END; 


HideWindow (gDlogPtr); 
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SetPort (gGrafPtr); 
IF gOptionleTrace] THEN 
TraceNbr( ‘Returning ',ORDCsItem.Enum2); 
IF (sitem.Enum >= kI temFst) 
AND (sItem.Enum <= kItemLst) THEN 
MainDlogWorkRequested := sItem.Enum 
ELSE 
MainDlogWorkRequested := eQuit; 
END; 
END. 
*Patrol.p^ 
UNIT Patrol; 
INTERFACE 
USES 
MemTypes, QuickDraw, OSIntf , Too1Intf , PackIntf , Globals; 
PROCEDURE BuildDirname; 
PROCEDURE InitPatrols; 
PROCEDURE PatrolDirectoriesCpOnly IDeep: BOOLEAN); 
PROCEDURE PatrolEverything; 
PROCEDURE PatrolFiles; 
IMPLEMENTATION 
($R-) 
CONST 
kPatsInitd 
TYPE 
TOver lapp ingPBs 
RECORD 
CASE INTEGER OF 
0: CfPBRec: 
1: CfCPBRec: 
END; 


- 12345; 


HParamBlockRec); 
CInfoPBRec); 


VAR 
gAAPatImpl,gZZPatImp]!: SignedByte; 
gAppDirId,gInitdFlag,gSysDirId: LONGINT; 
gAppVRef Num, gOr igWDRefNum,gSysVRefNum: INTEGER; 


gOnly 1Deep: BOOLEAN; 
gPBs: TOver lappingPBs; 
gSFLst: SFTypeList; 
gWDPBRec: WDPBRec; 
VAR 
sErr: 05Егг; 
sLen: INTEGER; 
sName : 517255; 
sPBs: TOverlappingPBs; 
BEGIN 


IF gOption[eTrace] THEN 
Trace( ‘BuildDirname’ ); 
WITH sPBs, fPBRec, fCPBRec 00 

BEGIN 
sPBs 
ToNamePtr 
ioVRef Num 
gCurrDirname 
IF gHFS THEN 
BEGIN 
ioFDirIndex 
ioDrPar ID 
REPEAT 
ioDrDirId := ioDrParID; 
sErr := PBGetCat Inf oCef CPBRec, FALSE); 
IF €sErr € NoErr) THEN 
EXITCBuildDirname); 
sLen := LENGTH(sName?* 14LENGTHCgCurrD irname); 
IF (sLen <= 255) THEN 
gCurrDirname := CONCATCsName, ’:’,gCurrDirname); 
UNTIL io0rDirId = 2; 
END 
ELSE 
BEGIN 
sErr := PBGetVolCefPBRec,FALSE); 
IF (sErr = NoErr) THEN 
gCurrDirname := CONCATCSName, ’: ^); 
END; 


gPBs; 

@sName; 
gCurrWORef Num; 
02. 


*1 
0; 
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END; 


END; 

BEGIN 

gActiveSelf := 
(gCurrVRefNum = gAppVRefNum) AND 
CgCurrDirId = gAppDirId) AND 
(gCurrFilename = StringPtr(kCurApName)^); 

gActiveSys := 
(gCurrVRefNum = gSysVRefNum) AND 
(gCurrDirId = gSusDirId) AND 
(gCurrFilename = StringPtr(kSusResName) ); 

gCurrFileDeleted := FALSE; 

ProcessFile; 

END; 


PROCEDURE FloatwWDDeeper(pDrDirId: LONGINT); 
BEGIN 
IF gOption[eTrace] THEN 
TraceNbr('Begin FloatWDDeeper, WD = ', 
ORD4(gCurrWDRefNum)); 
WITH gPBs,fCPBRec DO 
BEGIN 
IF NOT((pDrDirId=0) OR (pDrDirId=2)) THEN 
BEGIN 
gWDPBRec.ioVRefNum := gCurrWDRefNum; 
gWDPBRec.ioWDDirId := 0; 
gError := PBCloseWDC@gWDPBRec, FALSE); 
IF (gError © NoErr) THEN 
BEGIN 
ErrorOSErrC'Couldn^t close WD’); 
EXITCF loatwDDeeper ); 
END; 
END; 
gWDPBRec. ioVRefNum := gCurrVRefNum; 
QWDPBRec. ioWDDirId :- ioDrDirId; 
gError := PBOpenWDC@gWDPBRec, FALSE); 
IF (gError € NoErr) THEN 
BEGIN 
ErrorOSErr( ‘Couldn’t open subdir WD’); 
EXITCF loatwDDeeper ); 
END; 
gCurrWDRefNum := gWDPBRec.ioVRefNum; 
END; 
IF gOption[eTrace] THEN 
TraceNbr( ‘End — FloatWDDeeper, WD 
ORD4CgCurrWDRef Num 2); 


END; 
PROCEDURE FloatWDShallower(pDrDirId: LONGINT); 
BEGIN 
IF  gOptionteTrace] THEN 
TraceNbr( ‘Begin FloatWDShallower, WD = ', 
ORD4(gCurrWORefNum)); 
WITH gPBs, fCPBRec 00 
BEGIN 
gError := PBCloseWDC@gWDPBRec, FALSE); 
QWOPBRec. ioVRefNum := gCurrWDRefNum; 
gWDPBRec.ioWDDirId := Ø; 
IF (gError © NoErr) THEN 
BEGIN 
Error0SErr(‘Couldn’t close subdir WD’); 
EXITCFloatwDShal lower 2; 
END; 


IF (pDrDirId = 0) 
OR CpDrDirId = 2) THEN 
gCurrWDRefNum := gOrigWDRefNum 
ELSE 
BEGIN 


QNDPBRec. ioVRefNum := gCurrVRefNum; 
gWOPBRec.ioWDDirId := pDrDirld; 
дЕггог := PBOpenWDC@gWDPBRec, FALSE); 
IF (gError € NoErr) THEN 

BEGIN 

ErrorOSErrC'Couldn^t reopen WD’); 

EXITCF loatwDShal lower 2; 
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END; 
gCurrWDRefNum := gWDPBRec. ioVRefNum; 
END; 
END; 
IF gOption[eTrace] THEN 
TraceNbr( ‘End FloatWDShallower, WD = ', 
ORD4CgCurrWDORef Num )); 
END; 
PROCEDURE GetActualDirIKpDrDirId: LONGINT); 
BEGIN 
WITH gPBs,fCPBRec 00 


BEGIN 

ioDrDirId := pDrDirld; 
ioFDirIndex := -1; 

ioVRefNum := gOrigWDRefNum; 


gError := PBGetCatInfoCef CPBRec,FALSE); 
IF (gError € NoErr) THEN 
BEGIN 
ErrorOSErrC'Couldn't GetActualDirId^2; 
EXITCGetActualDirId2; 
END; 
gCurrDInfo := ioDrUsrWds; 
gCurrDirId := ioDrDirId; 
IF gOption[eTrace] THEN 
TraceNbrC'ActualDirID = ',gCurrDirId); 
END; 
END; 
1 . 
BEGIN 
IF gQptionleTrace] THEN 
Trace(‘InitPatrols’); 
WITH gPBs, fPBRec, ҒСРВКес DO 


BEGIN 
ZeroOutRange(@gAAPatImp1,@gZZPatImp1); 
gHFS ‚= TWordPtr(kSFCBLen)* > Ø; 


ioNamePtr := @gCurrFilename; 
IF gHFS THEN 

BEGIN 

gError := GetVRefNum 
(TWordPtr(kSusMap)*,gSusVRefNum); 

IF (gError € NoErr) THEN 
Error0SErr(‘Couldn’t get act sys vol’); 

ioVRefNum := gSysVRefNum; 

gError ‚= PBHGetVInfoC@fPBRec, FALSE); 

IF (gError € NoErr) THEN 
Error0SErr(‘Couldn’t get act sys dir’); 

IF (fPBRec.ioVFndrlnfo[1] = Ø) THEN 
Еггог05Егг( ‘Boot vol not Blessed’); 

gSysDirId :- ioVFndrInfoL 11; 

gError := PBHGetVolC@fPBRec, FALSE); 

IF (gError € NoErr) THEN 
ErrorOSErrC'Couldn^t get own Dirld’); 

gAppDirId :- ioDirId; 

gCurrDirId := ioDirId; 

gCurrWORefNum := ioVRefNum; 

ioVollndex := 0; 

gError ‚= PBHGetVInfoC@fPBRec, FALSE); 

IF (gError © NoErr) THEN 
Еггог05Егг( ‘Couldn’t get own VInfo’); 

gAppVRefNum := ioVRefNum; 


END 
ELSE 
BEGIN 
gSysVRefNum := TWordPtr(kBootDrive)*; 
gError := PBGetVol(C@fPBRec, FALSE); 


IF (CgError © NoErr) THEN 
ErrorOSErr(‘Couldn’t get own Vol’); 

gAppVRefNum := ioVRefNum; 

gCurrWDRefNum := ioVRefNum; 

gAppDirId j 

gsysDir Id 

gCurrDirId 

END; 
BuildDirname; 


пи M 
MPR H I 
. Wwe 
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gCurrFilename := StringPtr(kCurApName)` ; 


ioFDirIndex := Ø; 

ioDirId = 0; 

ioVRefNum = gCurrWDRefNum; 

gError := PBGetF InfoC@fPBRec, FALSE); 


IF (gError © NoErr) THEN 
Еггог05Егг( ‘Couldn’t get own FInfo’); 


gCurrF Info := ioFlFndrInfo; 
gActiveSelf := TRUE; 
gActiveSys := FALSE; 
gWDPBRec.ioWDProcID := $506 17472; ('Patr") 
gInitdFlag := kPatsInitd; 
END; 

END; 


PROCEDURE  PatrolDir(pDrDirId: LONGINT); 
VAR 
sIndex: INTEGER; 
BEGIN 
IF gOption[eTrace] THEN 
TraceNbr(C'PatrolDir ',pDrDirId); 
WITH gPBs,fCPBRec DO 
BEGIN 
IF CgInitdFlag o kPatsInitd) THEN 
BEGIN ( shouldn't happen ) 
ErrorOSErrC'InitPatrols not done’); 
EXITCPatrolDir2; 
END; 
IF gHFS THEN 
BEGIN 
gCurrDirId := pOrDirId; 
GetActualDirIdCpOrDirId); 
IF (gError © NoErr) THEN 


EXITCPatrolDir?); 
END 
ELSE 
gCurrDirId := 2; 
BuildDirname; 
DirectoryBegins; 
sIndex := 1; 
REPEAT 
gCurrIndex := sIndex; 
ioFDirIndex := sIndex; 
ioDrDirId = 0; 
ioVRefNum := gCurrwDRefNum; 


gError :- PBGetFInfoCefPBRec,FALSE); 
IF (gError = NoErr) THEN 
BEGIN 
gCurrFInfo := ioFlFndrInfo; 
CallProcessF ile; 
END 
ELSE IF (gError € fnfErr) THEN 
BEGIN 
ErrorOSErrC'Couldn't get a file’); 
EXITCPatrolDir); 
END; 
IF NOTCgCurrFileDeleted) THEN 
INC(s Index); 
UNTIL (дЕггог © NoErr) OR gAbortPatrol ; 
IF gAbortPatrol THEN 
EXITCPatrolDir?; 
IF (gError © fnfErr) THEN 
BEGIN 
ErrorOSErr( ‘Error at end of files’); 
EXITCPatrolDir); 
END; 
gError := NoErr; 
IF gHFS AND NOTCgOnlyiDeep) THEN 
BEGIN 


sIndex := 1; 

REPEAT 
gCurrIndex := sIndex; 
ioFDirIndex := sIndex; 
ioDrDirId := 0; 
ioVRefNum := gCurrWDRefNum; 
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gError := PBGetCatInfoC@fCPBRec, FALSE); 
IF (gError = NoErr) THEN 
BEGIN 
IF BTstCORD4CioF1Attrib),4) THEN 
BEGIN 
FloatWDDeeper (pDrDirId); 
IF (gError © NoErr) THEN 
EXITCPatrolDir); 
PatrolDirCioDrDirId); 
IF (gError © NoErr) 
AND CpDrDirId «> Ø) 
AND CpDrDirId © 2) THEN 
EXITCPatrolDir); 
FloatWDShallower(CpOrDirId2; 
IF (gError © NoErr) THEN 
EXITCPatrolDir2; 
END; 
END 
ELSE IF (gError © fnfErr) THEN 
BEGIN 
ErrorOSErrC'Couldn^t get a dir’); 
EXITCPatrolDir); 
END; 
INCCsIndex); 
UNTIL CgError <> NoErr) OR gAbortPatro!; 
IF gAbortPatrol THEN 
EXITCPatrolDir); 
IF (gError © fnfErr) THEN 
BEGIN 
ErrorOSErr( ‘Error at end of subdirs’); 
EXITCPatrolDir); 
END; 
gError := NoErr; 
gCurrDirId := pDrDirId; 
GetActualDirId(pDrDirId); 
IF СдЕггог © NoErr) THEN 
EXIT(PatrolDir); 
BuildDirname; 
END; 
DirectoryEnds; 
END; 


END; 
PROCEDURE PatrolDirectories(pOnly 1Deep : BOOLEAN); 
BEGIN 

IF gOptionleTrace] THEN 


TraceC'PatrolDirectories '); 


WITH gPBs, fPBRec, fCPBRec,gSFRep 00 


BEGIN 
IF (gInitdFlag © kPatsInitd) THEN 
BEGIN ( shouldn't happen ) 
ErrorOSErrC'InitPatrols not done’); 
EXIT(PatrolDirectories); 
END; 
gOnlulDeep := pOnlulDeep; 
SFGetFile 
(gSFGetPt, "^, NIL,-1,gSFLst,NIL, gSFRep); 
WHILE good DO 
BEGIN 
IF gHFS THEN 
BEGIN 
ioVRefNum := gSFRep.vRefNum; 
ioVolIndex := 0; 
gError :- PBHGetVInfo(@fPBRec,FALSE); 
IF (gError © NoErr) THEN 


BEGIN 
Error0SErr(‘Couldn’t get own VInfo’); 
LEAVE; 
END; 
gCurrVRefNum := ioVRefNum; 
END 
ELSE 
gCurrVRefNum := vRefNum; 
gCurrWDRefNum := vRefNum; 
gOrigWDRefNum := vRefNum; 


283 


PatrolBegins; 
PatrolDir(0); 
PatrolEnds; 
IF (gError © NoErr) THEN 
LEAVE; 
SFGetFile 
CgSFGetPt, ^^, NIL,-1,gSFLst,NIL, gSFRep?; 
END; 
gError := NoErr; 


r 
VAR 
sIndex: INTEGER; 
BEGIN 
IF gOption[eTrace] THEN 
TraceC'PatrolEverything “2; 
WITH gPBs,fPBRec,f CPBRec DO 
BEGIN 
IF (gInitdFlag © kPatsInitd) THEN 
BEGIN ( shouldn’t happen } 
Error0SErr(‘InitPatrols not done’); 
EXITCPatrolEverything); 


END; 
gonlyiDeep := FALSE; 
PatrolBegins; 
ToVRef Num := 0; 
sIndex о; 
REPEAT 
gCurrindex := sIndex; 
ioVollndex := sIndex; 
gError := PBGetVInfoC@fPBRec, FALSE); 
IF СдЕггог = NoErr) THEN 
BEGIN 
gCurrVRefNum := ioVRefNum; 
gCurrWDRefNum := ioVRefNum; 
gOrigWDRefNum := ioVRefNum; 
PatrolDir(2); 


IF (gError «€ NoErr) THEN 
EXITCPatrolEverything); 
INCCsIndex); 
END 
ELSE IF СдЕггог © nsvErr) THEN 
BEGIN 
ErrorOSErrC'Couldn^t get а volume’); 
EX1T(PatrolEverything); 
END; 
UNTIL gError «> NoErr; 
IF (CgError O nsvErr) THEN 
BEGIN 
ErrorOSErr( ‘Error at end of volumes’); 
EXITCPatrolEverything); 
END; 
gError := NoErr; 
PatrolEnds; 
END; 
END; 


VAR 
sPrevDirId: ^ LONGINT; 
sPrevVRefNum: INTEGER; 
sPrevWDORef Num : INTEGER; 
R R llPrevDirEnd; 
VAR 
sTempDirId: ^ LONGINT; 
sTempVRefNum: INTEGER; 
sTempWDRefNum: INTEGER; 


BEGIN 

IF CsPrevWDRefNum € Ø) THEN 
BEGIN 
sTempDirId ‚= gCurrDirId; 
sTempVRefNum := gCurrVRefNum; 
sTempWDRefNum := gCurrWDRefNum; 
gCurrDirId := sPrevDirId; 
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gCurrVRefNum := sPrevVRefNum; 
gCurrWDRefNum := sPrevWDRefNum; 
DirectoryEnds; 
gCurrDirId ‚= sTempDirId; 
gCurrVRefNum := sTempVRefNum; 
gCurrWDRefNum := sTempWDRefNum; 
END; 
END; 
BEGIN 


IF gOptionteTrace] THEN 
TraceC'PatrolFiles ‘); 
WITH gPBs,fPBRec,f CPBRec, gSFRep 00 
BEGIN 
IF (glnitdrlag © kPatsInitd) THEN 
BEGIN ( shouldn’t happen ) 
ErrorOSErrC'InitPatrols not done’); 


EXIT(CPatrolFiles); 
END; 
PatrolBegins; 
sPrevWDRefNum := 0; 
SFGetFile 


CgSFGetPt, ’’,NIL,-1,gSFLst,NIL, gSFRep); 
WHILE good DO 

BEGIN 

IF ӘНЕЅ THEN 
BEGIN 
ioVRef Num 
ioDrDirId 
ioFDirIndex 1; 
gError := PBGetCatInfoC@fPBRec, FALSE); 
IF СдЕггог © NoErr) THEN 


gSFRep . vRef Num; 


2 


BEGIN 
ErrorOSErrC'Couldn^t get Dirld’); 
LEAVE; 
END; 
gCurrDirId := ioDrDirId; 
ioVollndex := 0; 


gError := PBHGetVInfoCefPBRec, FALSE); 
IF (gError © NoErr) THEN 


BEGIN 
ErrorOSErr( ‘Couldn’t get VInfo’); 
LEAVE; 
END; 
gCurrVRefNum := ioVRefNum; 
END 
ELSE 
BEGIN 
gCurrDirld := 2; 
gCurrVRefNum := vRefNum; 
END; 
gCurrFilename := fName; 
gCurr Index := Ø; 
gCurrwDRefNum := vRefNum; 
IF (sPrevWwDRefNum <> gCurrWDRefNum) THEN 
BEGIN 
CallPrevDirEnd; 
BuildDirname; 
DirectoruBegins; 
sPrevDirId ‚= gCurrDirld; 
sPrevVRefNum = gCurrVRefNum; 
sPrevWDRefNum := gCurrWDRefNum; 
END; 
ioDrDirId := gCurrDirId; 
ioFDirIndex := gCurrIndex; 
ioVRefNum := gCurrWDRefNum; 


gError := PBGetFInfoCefPBRec,FALSE; 
IF (CgError © NoErr) THEN 


BEGIN 
ErrorOSErrC'Couldn't get FInfo^); 
LEAVE; 
END; 
gCurrFInfo := ioFlFndrInfo; 
CallProcessFile; 


IF gAbortPatrol THEN 
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LEAVE; 
SFGetFile 


(gSFGetPt, ’’,NIL,-1,gSFLst,NIL, gSFRep); 


END; 

gError :- NoErr; 

CallPrevDirEnd; 

PatrolEnds; 

END; 
END; 
END. 

*SecurityPatrol.p* 


PROGRAM SecurityPatrolCOUTPUT); 
USES 


MemTypes, QuickDraw, OSIntf , Too1Intf ,PackIntf ,CodeSizeLimits,Globals, 


MainDlog,PasL ibIntf, Patrol; 


($R-) 

CONST 
kPreprocessSe1f = TRUE; 
kAwaitVerification = FALSE; 

VAR 
gInitSecPatDone, gRptF ileOpen: BOOLEAN; 
gScrDmpEnbPtr : Ptr; 
gScrDmpEnbSave : SignedByte; 
o: Text; 

PROCEDURE PreprocessSelf ; FORWARD; 


PROCEDURE Wryte(pStr: Str255); 
PROCEDURE WryteChar(pChar : CHAR); 


PROCEDURE WryteEoln; FORWARD; 


PROCEDURE WryteLn(pStr: Str255); 


PROCEDURE WruteNbr(pNbr:LONGINT; ;pNbrDigits: INTEGER); FORWARD; 
FORWARD; 


PROCEDURE WryteTypeCpType: ResType); 
($2*) 
PROCEDURE ExitSecurityPatrol; 
BEGIN 
IF gOption[eTrace] THEN 
Trace( ‘ExitSecurityPatrol’); 
gScrDmpEnbPtr^ := gScrDmpEnbSave ; 
IF gRptFileOpen THEN 
CloseCo); 
ExitToShe11; 
END; 
($2-) 
VAR 
sConfig: ^ LONGINT; 
BEGIN 
MaxApp 1Zone; 
MoreMasters; MoreMasters; MoreMasters; 
gInitSecPatDone := FALSE; 


QRptFileOpen :* FALSE; 
gScrDmpEnbPtr :- Ptr(kScrDnpEnb); 
gscrDmpEnbSave :- gScrDmpEnbPtr^; 
gScrDmpEnbPtr^ := Ø; 
Textbook(@thePort); 


Write (“SecurituPatrol is а Mac virus ‘); 
Write C'detector. ‘); 

TextFace( [bold, extend]); 

WriteLn( ‘Use at your own risk. ‘); 
TextFaceCE 12; 


Write (“The Save As... dialog below is '); 


WriteLnC'to save error reports."); 
PLF lushCOUTPUT); 
PauseBr ief ly; 
InitGlobals; 
gOptionleBeeps] 
gDisabledleFgPrC] 
InitMainDlog; 
InitPatrols; 
sConfig := BAndCORD4(Ptr(kSPConf ig)" ), $F); 
IF (sConfig = useFree) 
OR (sConfig = useAsync) THEN 

SFPutF ile 


TRUE; (override..) 
TRUE; (.defaults) 


(gSFPutPt, "Filename, or cancel to print’, 


'SecurityPatrol Report’, NIL, gSFRep) 
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FORWARD; 
FORWARD; 


FORWARD; 


ELSE 
SFPutF ile 
(gSFPutPt,'Filename, or cancel to quit’, 
‘SecurityPatrol Report’,NIL,gSFRep); 
WITH gSFRep DO 
IF good THEN 
BEGIN 
gCurrWORefNum := vRefNum; 
BuildDirneme; 
Кенг i teCo, CONCATCgCurrD irname, fName)); 
END 
ELSE 
IF (sConfig = useFree) 
OR (sConfig = useAsunc) THEN 
ReWriteCo, ‘PRINTER: ^) 
ELSE 
BEGIN 
WriteLnC'Run cancelled. ^); 
PLFlushCOUTPUT); 
PauseBr ief ly; 
ExitSecurityPatrol; 
END; 
gRptFileOpen := TRUE; 


Wryte (“This copy of security Patrol 1.8 '); 


Wryte (715 being maintained by °); 
TextFace( [bold, extend]); 
gPgmrname :- “(your name here>’; 
WryteLn(gPgmrname ); 
TextFaceCL 1); 
Wryte (“The following run was done on ‘); 
GetTimeCgDateTimeRec); 
WITH gDateTimeRec DO 
BEGIN 
year := year mod 100; 
WryteNbr (month, 2); 
WryteChar(‘/’); 
WryteNbr (dau, 2); 
WryteCharC'/^); 
WryteNbr Cyear, 2); 
Wryte (' at '); 
WryteNbr (hour, 2); 
WryteChar(’:’); 
IF minute < 10 THEN 
WryteChar (‘8’); 
WryteNbr (minute, 1); 
WryteLn (7.7); 
END; 
IF kPreprocessSelf THEN 
PreprocessSelf 
SE 


NruteLn('Didn t perform self-tests.’); 
gInitSecPatDone := TRUE; 
END; 
DUR r f; 
van 
INTEGER; 


SCIPtr, sEntActual ,sEntShou1dB, sOf f Actual ,sOffShouldB:LONGINT; 


sResTupe: ResTupe; 

sSave: TMainOpt; 

PROCEDURE Abort(pStr: Str255); 
BEGIN 

ErrorBegins(pStr); 

WruteEoln; 

CommentBegins; 

WryteLn( ‘Assuming infected. ^); 
CommentBegins; | 

Wryte (“Contact б; 

Wryte (gPgmrname); 

WrytelnC' to be sure. ’); 
CommentBegins; 

Wryte ('(These msgs apply to ^); 
Wryte (CgCurrFilename); 

WryteLn(’ itself, not to your system. )’); 
CommentBegins; 


д 
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gOption[eAwait] 
gOption[eBeeps]) 
ErrorEnds(4); 
ExitSecurituPatrol; 
END; 

BEGIN 


TRUE ; 
TRUE ; 


BlockMove(@g0ption, @sSave, SIZEOF CTMainOpt)); 
ZeroOut (@gOption, SIZEOF CTMainOpt)); 


gOptionfeRmVir] := TRUE; 
( gOptionfeTrace] := TRUE; ) 
IF gOption[eTrace] THEN 
Trace( *PreprocessSelf ^); 
GetCodeSizeLimits; 
GetRsrc(@gCoded, CODE ,8,ResId); 
IF (gCode®.fFlag € kRsrcHdlValid) THEN 
AbortC'Unable to get own CODE 9’); 
IF NOTCCode?IsValid) THEN 
AbortC'Found unexpected CODE 0 header’); 
LookForKnownV iruses; 
FOR i := 1 TO Count 1Туреѕ 00 
BEGIN 
Get 1IndTypeCsResType, i); 
IF CsResType = 'SIZE') THEN 
BEGIN 
IF  CCount iResourcesC'SIZE^) > 1) THEN 
AbortC'Too many SIZE resources’); 
GetRsrc(@gCurrRsrc, ^SIZE', 1, Index); 
IF  CgCurrRsrc.fSize > 10) THEN 
Abort( ‘SIZE resource too large’); 
ReleaseRsrcCégCurrRsrc); 
END 
ELSE IF CsResType <> ‘CODE’) THEN 
BEGIN 
ErrorBeginsC'Found a rsrc of type ‘); 
WryteTypeCsResType); 
ErrorEnds(C2); 


Abort (“Onlu CODE and SIZE allowed’); 


END; 

END; 

WITH TJTHdlCgCode2 . fHd15^^, fJTEntryL 11 DO 

BEGIN 

IF CfNorBytesInTable € gJTSize) THEN 
BEGIN 
ErrorBeginsC^Jump table size is ‘); 
WryteNbr CfNbrBytesInTable, 1); 
Wryte (^, should be ‘); 
WryteNbr (gJTSize, 1); 
ErrorEnds(@); 
Abort ‘Invalid Jump Table size’); 
END; 

IF NOTCJTEIsValidCefJTEntry[ 1))) THEN 
AbortC^Invalid Jump Table entry’); 

IF (fSegld © 1) THEN 
BEGIN 
ErrorBegins( ‘Enters at CODE '); 
WryteNbrCfSegId, 1); 
Wryte С“, should enter at CODE 1’); 
ErrorEnds(@); 
Abort (“Invalid start address’); 
END; 

sOffActual := 4 + fOffset; 

END; 

WITH gCurrRsrc DO 

BEGIN 

GetRsrc(@gCurrRsrc, CODE ^, 1,ResId); 

IF (fFlag © kRsrcHdlValid) THEN 
AbortC'Couldn/t look at own CODE 1'); 


sCIPtr := BANDCS$OOFFFFFF , ORD4CfHd1* 25; 


sEntActual := sCiPtr + sOffActual; 
IF (TWordPtrCsEntActual)* = $4EFA) THEN 
BEGIN 
sOffActual := 
sOf fActual+2+TWordP tr CsEntActual+2)*; 
sEntActual := ӨСІРіг + sOffActual; 
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END; 
sEntShouldB := gEntryPoint; 
sOffShouldB := sEntShouldB - sCiPtr; 
IF CsEntActual € sEntShouldB) THEN 
BEGIN 
ErrorBegins( ‘Invalid start address’); 
WryteEoln; 
CommentBegins; 
Wryte (‘Enters at address $’); 
Shor tHexDump(@sEntActual, 4); 
Wryte (° (CODE 1 + $); 
Shor thexDump(@sOf f Actual, 4); 
Wyte (02 $); 
ShortHexDump(Ptr(sEntActual),4); 
WryteEoln; 
CommentBegins; 
Wryte (‘Should enter at $); 
Shor tHexDump( @sEntShou1dB, 4); 
Wryte С“ (CODE 1 + $”; 
Shor tHexDump( @sOf f Shou1dB, 4); 
Wryte (02 $); 
Shor tHexDump(PtrCsEntShouldB ), 4); 
WryteEoln; 
CommentBegins; 
Wryte (“CODE 1 begins at $); 
Shor tHexDumpC8sC IP tr, 4); 
ErrorEnds(@); 
Abort (“This is not a user error’); 
END; 
ReleaseRsrc(@gCurrRsrc); 
END; 


ReleaseRsrc(CégCode2); 
IF (Count IResourcesC'CODE / 5» gMaxCode* 1) THEN 


AbortC'Too many CODE resources."); 


IF kAwaitVerification THEN 


BEGIN 

ErrorBeginsC'The following are the ‘); 
Wryte ('*fingerprints^ of '); 

Wryte (gCurrFilename); 

Wryte (° itself: ); 

ErrorEnds(C0); 

END; 


FOR i := @ TO gMaxCode DO 


WITH gCurrRsrc DO 

BEGIN 

GetRsrcCégCurrRsrc, "CODE", i, ResId); 

IF (fFlag  kRsrcHdlValid) THEN 
AbortC'Couldn^t look at next CODE’); 

IF (fSize > gSizeLimit[iJ) THEN 
BEGIN 
ErrorBegins( ‘Failed a CODE size test’); 
WryteEoln; 
CommentRsrcBeginsCegCurrRsrc?; 
Wryte (“size is ‘); 
WryteNbr(CfS ize, 1); 
Wryte С°, which exceeds its б; 
WryteNbr(gSizeLimitlil, 1); 
WryteLn (° size limit./’); 
Abort( ‘May contain an imbedded virus’); 
END; 

IF kAwaitVerification THEN 
BEGIN 
ProcessCurrRsrc; 
CommentFgPrRsrc(@gCurrRsrc); 
END; 

ReleaseRsrc(@gCurrRsrc); 

END; 


IF kAwaitVerification THEN 


BEGIN 

ErrorBegins(‘Time to make a decision: ^); 
WryteEoln; 

CommentBegins; 

WryteLn( ‘Verify fingerprints if you can’); 
CommentBegins; 
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WruteLn( “Press command-period to abort’); 
CommentBegins; 
WryteLn( ‘Press anu other key to continue’); 
CommentBegins; 
gOption[eAwait] := TRUE; 
ErrorEnds(@); 
IF gAbortPatrol THEN 
BEGIN 
PauseBr ief ly; 
ExitSecurityPatrol; 
END; 
END; 
WryteLn( ‘Passed all current self-tests. ’); 
PauseBr ief ly; 
BlockMoveCésSave, 6g0pt ion, SIZEOF CTMainOpt2); 
END; 


($2*) 
PROCEDURE  WriteFilenameToReport; 
BEGIN 


WITH gReportFlags DO 
IF NOTCfWroteFilename) THEN 
BEGIN 
IF NOTCfWroteDirname) THEN 
BEGIN 
WriteLnCo, gCurrDirname?); 
fWroteDirname := TRUE; 
END; 
WriteCo,gInd, gCurrFilename); 
IF gActiveSelf THEN 
BEGIN 
WriteCo,^ (Active Self 2^); 
IF gInitSecPatDone 
AND NOTCkProcessSelf) THEN 
WriteCo,^ skipped’); 
END 
ELSE IF gActiveSys THEN 
WriteCo,^ (Active System)’); 


WriteLn(o); 
fWroteFilename := TRUE; 
END; 
END; 
R R i teF i meToScr 
BEGIN 


WITH gScreenFlags DO 
IF NOTCfWroteFilename) THEN 
BEGIN 
IF NOTCfWroteDirname) THEN 
BEGIN 
WriteLn(gCurrDirname); 
fWroteDirname :- TRUE; 
END; 
Wr iteCgInd,gCurrF ilename?); 
IF gActiveSelf THEN 
BEGIN 
WriteC' (Active Self 2^); 
IF gInitSecPatDone 
AND NOTCkProcessSelf) THEN 
WriteC' skipped’); 
END 
ELSE IF gActiveSys THEN 
WriteC' (Active System)’); 
WriteLn; 
PLFlushCOUTPUT); 
fWroteFilename := TRUE; 
END; 
END; 
PROCEDURE Wrute(pStr: Str255); 
BEGIN 
Write(pStr); 
IF gRptFileOpen THEN 
Write(o,pStr); 
END; 
PROCEDURE WryteChartpChar : CHAR); 
BEGIN 
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WriteCpChar ); 

IF gRptFileOpen THEN 
WriteCo, pChar ); 

END; 


WriteLn; 
PLFlushCOUTPUT); 
IF gRptFileOpen THEN 
BEGIN 
WriteLn(o); 
END; 
END; 
R R 11 
BEGIN 
IF gRptFileOpen THEN 
WriteFilenameToReport; 
WriteFilenameToScreen; 
END; 
R r ilen 
BEGIN 
WriteFilenameToScreen; 
END; 
PROCEDURE — WryteLn(CpStr: 517255); 
ВЕСІМ 
WriteLn(pStr); 
PLF lushCOUTPUT); 
IF  gRptFileOpen THEN 
BEGIN 
WriteLn(o,pStr); 
END; 
END; 
PROCEDURE WryteNbr(pNor: LONGINT; pNbrDigits: INTEGER); 
BEGIN 
WriteCpNbr :pNbrDigits); 
IF gRptFileOpen THEN 
WriteCo,pNbr:pNbrDigits); 
END; 
PROCEDURE WruteType(pType: | ResType); 
BEGIN 
WriteCpType); 
IF gRptFileOpen THEN 
WriteCo, pType); 
END; 
ROCEDUR j 
BEGIN 
END; 
BEGIN 
InitSecuritgPatro!; 
WHILE TRUE DO 
BEGIN 
gAbortPatrol := FALSE; 
CASE MainDlogWorkRequested OF 
eDirs: PatrolDirectories (FALSE); 
eDiry: PatrolDirectories (TRUE); 
eEvery: PatrolEverything; 
eFiles:  PetrolFiles; 
OTHERWISE LEAVE; 
END; (CASE) 
END; 
WryteEoln; 
WrytelnC Cx x00xnsoosoxosooooeooooeoeoepboooeoeo ? 3j 
WryteEoln; 
WryteLn (“Totals over all patrols: ^); 
ListCountsCégTotals); 
ExitSecurityPatrol; 


SecurityPatrol.Link CTNL 2.5 only) 
IPAS$Xfer 


SecuritgPatrol 
PAS$Library 
MacIntf 
MacIntfGlue 
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BitProcs 
CodeSizeLimits 
Globals 
MainDlog 

PasL ibIntf 
Patrol 

( 
Globals/Globals 
( 


BitProcs/F ingerpr int 
Globals/F ingerpr int 
/End 


plis i LE (ТМ. II Only) 


SecurityPatrol.p.o J à 
CodeSizeLimits.p д 


Globals.p д 
MainDlog.p д 
Patrol.p д 
SecurituPatrol.p 
TMLPascal SecurituPatrol.p 
CodeSizeLimits.p.o f à 
CodesSizeLimits.p 
TMLPascal CodeSizeLimits.p 
Globals.p.o f ò 
j rint.i 
Globals.p 
TMLPascal Globals.p 
MainDlog.p.o f д 


288 


Globals.p à 
MainDlog.p 
TMLPasal MainDlog.p 


Patrol.p.o f à 


Globals.p à 
Patrol.p 
TMLPascal Patrol.p 


SecurituPatrol ff д 


CodeSizeLimits.p.o д 
Globals.p.o д 
MainDlog.p.o д 
Patrol.p.o д 
SecurituPatrol.p.o 


Link -w -t ‘APPL’ -c 7229227 д 
_ F Ч ` 


-r 1 = 


SecurityPatrol.p.o à 
CodeSizeLimits.p.o à 


Globals.p.o д 
MainDlog.p.o à 
Patrol.p.o à 


" (Libraries) "Runtime.o ò 


" (Libraries) "Interface.o д 

" (Libraries) "ObjLib.o д 
"(ТМІРІ ibraries)"TMLPasLib.o à 
"(ТМІРІ ibraries) "SANEL ib.o à 


-о SecurityPatrol 
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Pascal Procedures 


How To Write a Font Tool for MPW тм. pascat 


[Randy Leonard is currently employed by TML Systems, Inc. 
while completing his Master’ s thesis in computer science at the 
University of Central Florida. His thesis involves improving the 
efficiency of several key algorithms in constructive solid geome- 
try (CSG). The thesis is written entirely with TML Pascal II and 
he uses several of his own MPW Tools to aid in his development.] 


The introduction of the Macintosh Programmer’s Workshop 
(MPW) v3.0 this January requires that we revisit this program- 
ming environmentand study its new and exciting features as well 
as the significant features of previous versions of the product. 
This article discusses how the MPW environment can be en- 
hanced with the addition of your own integrated programming 
tools. The type of commands introduced here are capable of 
executing in the background while running MPW v3.0. This 
capability enables you to continue your most important task in 
the foreground while such tasks as compiling and linking of 
programs occur in the background. Indeed, the tool introduced 
here may also run in the background. 


Macintosh Programmer’s Workshop 

The Macintosh Programmer’s Workshop is the official 
Macintosh development environment from Apple Computer, 
Inc. The MPW Shell is a complete development system for the 
Macintosh that includes, among other things, a multi-windowing 
text editor and acommand processor. Also included with MPW 
is a linker, make facility, resource compiler, resource decom- 
piler, source code management system, and more. There is also 
complete online help as well as an optional graphical interface for 
Just about every command available in MPW. 

MPW has often times been accused of having a steep 
learning curve. The author believes this false accusation can be 
based upon two pretexts. The first is due to unfamiliarity with the 
product/if you come from Big Blue or have been inVAXinated, it 
might be familiar, but still not easy-ed]. The second is due to the 
extraordinary power that MPW can provide its advanced users 
via the command line environment and MPW's advanced com- 
mand processor. The truth of the matter is that MPW is as easy 
to learn and use as any other programming environment if you 
were to utilize only those features found in MPW that the other 
programming environments provide. 

The true beauty of MPW is found in its open architecture. 
That is, anyone can expand the functionality of MPW to suit his 
own needs. There exist two methods of adding new commands 
to MPW: scripts and tools. This two part article will demonstrate 
how to create new programming tools and how to fully integrate 
these tools into the MPW environment. This month's article will 
give the motivation for writing your own MPW tool and show 
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how it is done. Part two, to appear next month, will demonstrate 
how to integrate the tool into the MPW's online help facility and 
how to develop a graphical interface for the new command. 


MPW Tools 

Tools provide a method of adding commands that are not 
inherent to the MPW command processor. For example, the 
TML Pascal II compiler is an extension to the MPW environment 
and is therefore implemented as a tool. Other examples of MPW 
Tools are the canonical speller Canon and TMLPasMat. TML 
Systems, in fact, used these two tools to put the finishing touches 
on both its Source Code Library II and example programs found 
on the TML Pascal II distribution disk. Canon adjusts all 
identifiers in source code files so they have the same same 
capitalization as found in Inside Macintosh. TMLPasMat will 
format all Pascal source code files to a consistent format that you 
define. These two tools were especially helpful since program- 
ming styles of the programmers at TML Systems vary. 

However, we needed even more help in providing a consis- 
tent format for all source code files that left our office. As it turns 
out, some programmers at TML Systems prefer different fonts 
and different font sizes fortheir work. Some programmers would 
print their work on the laser writer reduced to 7596 while others 
would print at 100%. Some prefer different tab settings and still 
others have large screens on which to edit their programs. This 
last problem could be especially annoying to our customers with 
small screens since only a small part of the window of a text file 
would appear on their screen when they opened the file. Each 
customer could easily resolve the problem by resizing the win- 
dow for his screen, but what if the window appeared off-screen 
to begin with! 

Another problem unrelated to each programmer's taste was 
the problem of USYM resources. The TML Pascal II compiler 
writes symbol table information for separately compiled units to 
the resource fork of the main unit source code file as USYM 
resources. This is perhaps a more favorable solution than 
creating separate files to hold the information as other compilers 
do. Deletinga filethat contains symbol table information is easy, 
but how do you easily erase resources from the resource fork of 
a source code file? 

To solve the above problems, we developed an MPW tool 
that changed the font of MPW text files to any specified font and 
fontsize. Tab spacing is set to any defined value and the window 
is made to appear on any Macintosh screen with the top left corner 
slightly staggered from other windows and the bottom right 
cornerextending to the bottom right of the screen. The page setup 
is reset to print at 100%. All USYM and other resources are 
optionally deleted as well. We call this tool ChangeTextRes. 
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Below, we explain how to implement this tool, but first a little 
background. 


What Every Tool has in Common 

MPW Tools are usually invoked from the command line of 
the MPW Shell. The command line of an MPW command is 
simply the line on which the MPW command exists. Parameters 
are passed to the tool by placing them on the command line. A 
graphical interface for the tool, called the Commando, does exist, 
but is not typically used. The Commando interface for a tool is 
invoked by typing in the command name followed by the ellipses 
character (...). This character is obtained by holding the option 
key and pressing the semicolon. The implementation of a custom 
Commando interface for ChangeTextRes is discussed in next 
month’s article. 

Apple has defined several conventions for MPW Tools that 
allow them to work well together in an integrated fashion. First 
and most important is that a tool have some default behavior. 
Deviations from this default should result only from options 
specified on the command line. A command line option is simply 
a parameter found on the command line starting with the charac- 
ter ‘-’. For example, the resource decompiler tool DeRez is 
invoked by typing: 


DeRez filename 


where filename specifies any resource file at all. If you wish 
only to decompile only dialog resources, you would type: 


DeRez filename -only DLOG 


Now, only resources of type ‘DLOG’ will be decompiled. 
The behavior of the DeRez tool has been modified by the -only 
option. Many command line options may be specified, but the 
order in which they are given should never matter. 

Another rule is that tools are to run silently, they should 
require no interaction with the user to carry out its task. The only 
visual feedback from the tool should be in the form of a spinning 
cursor. The reasoning for these rules have their roots in the 
advanced capabilities of the MPW command processor. Should 
the reader wish to become a more powerful user of MPW, he is 
referred to the chapter “Using the Command Language” of the 
Macintosh Programmer’ s Workshop Reference. 


The Command Processor 

Each time a command is entered, the MPW command 
processor attempts to interpret it. If it is unsuccessful, the 
command processor assumes the command is either a tool, script, 
or an external application. Since we are writing a tool, we do not 
need to concern ourselves to much with the command processor, 
but there are a few features that need to be discussed. 

Before invoking an MPW tool, the command processor first 
attempts to interpret parts of the command line. Certain charac- 
ters have special meaning to the command processor. For 
example, the = (Option-x) character is a wild card character. If 
=.p is specified, the command processor will expand this to a 
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sequence of filenames that end with .p. The MPW Tool never 
sees the =.p parameter. Rather, it sees the sequence of filenames 
that match the =.p pattern! This not only increases a user's 
productivity, but also simplifies the writing of tools. 

Also allowed are special characters for I/O redirection, 
piping, and substitution of MPW Shell variables/very nice to 
have.-ed]. Knowledge of these features are not necessary for the 
average MPW user. See the Macintosh Programmer' s Work- 
shop Reference for more details. 

Three file variables are predefined for MPW Tools, input 
(standard input), output (standard input), and diagnostic. As 
expected, standard input is the Macintosh keyboard. Standard 
output and diagnostic output are both the current topmost 
window found in the MPW environment. 


How ChangeTextRes Works 

The underlying theory of ChangeTextRes is quite simple. 
The tool receives from the command line the name of each file it 
is to work on as well as any command line options that may exist. 
The resource fork of each MPW text file specified on the 
command line is deleted if the command option -d is also present 
on the command line. If the -d option is not specified then no 
resources of any files are ever deleted. ChangeTextRes will then 
change the file's font, font size, and tab setting. 

If ChangeTextRes is instructed to delete the entire resource 
fork with the -d option, there will no longer be any resource 
specifying the page setup or window size and position. If a file 
has no resource for page setup or file window position, the MPW 
Shell will assume default values. The default value for window 
position is to stagger the window’s top left corner and cover the 
rest of the screen. The -d option will delete all US YM resources 
created by the TML Pascal II compiler as well. 

ChangeTextRes assumes default values of Monaco, 9 point, 
and 3 for the font, font size, and tab setting, respectively. The user 
may change these values with the command line options -f, -s, 
and -t. The -f option, followed by a font name instructs 
ChangeTextRes to use that font name. The -s option followed by 
an integer value instructs ChangeTextRes to use the specified 
fontsize. And the -t option followed by an integer value instructs 
ChangeTextRes to use the specified tab setting. An error mes- 
sage is generated if an invalid font, a font size less than 1 or 
greater than 127, or a tab setting less than 1 or greater than 24 is 
specified. 

To use ChangeTextRes, type the command followed by all 
file names and options desired. Keep in mind the MPW Shell's 
filename expansion capabilities discussed above. For example: 


ChangeTextRes MyProject.proj 9.p 
-f Courier -s 12 -t 4 -d 


will delete all resources of all MPW text files ending with a 
р as well as the file MyProject.proj. The font for each file is set 
to Courier 9 point and the tab setting is set to 4. 


Accessing the Command Line 
Accessing the command line parameters from within a tool 
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is quite simple. The IntEnv unit defines two global variables used 
to access the command line parameters: argv and argc. The argv 
variable is a pointer to an array of pointers to strings. Argc tells 
how many parameters exist in the argv array. The argv array 
starts at element 0 and argc is always one greater than the actual 
number of parameters found on the command line. The expres- 
sion argv^[argc] is always equal to nil. The first parameter of the 
argv array (argv^[0]^) is the name of the MPW tool itself and is 
useful for error message generation. All parameters to the tool 
are stored in argv^[1]^ to argv^[argc-1]^. Itisup to the program- 
mer to read in command line parameters and to distinguish 
between regular parameters and command line options. The 
ChangeTextRes tool contains the procedure ReadComman- 
dLine to accomplish this task. 


procedure ReadCommandL ine; 
var 


argV Index : integer; 
arg : Str255; 
begin 


if argc = 1 then SuntaxError(9, '^)5; 
argVIndex := 1; 
while argVIndex < argc do begin 
arg := argv*largVIndex]*; 
if lengthCarg) © 0 then 
if arg[1] = -” then 
if lengthCarg) > 1 then 
HandleQptionCarg, argVIndex) 
else SyntaxError(8, “”); 
argVIndex := argVIndex + 1; 
end; ( while } 


end; 


In this routine, arg VIndex is used to traverse the command 
line parameters. Each time a command line option is found, the 
procedure HandleOption is called. HandleOption will read the 
option and set program global variables accordingly. Since 
options may require an additional parameter (e.g. the 
ChangeTextRes option -f, -s, and -t), HandleOption must have 
the ability to read the next parameter(s) on the command line and 
increment argVIndex accordingly. If an invalid command line 
option or invalid value corresponding to a valid option is found, 
HandleOption will generate an error and terminate the program. 


Rewriting a File's Resource Fork 

The sole purpose for ChangeTextRes is to rewrite part or all 
of a file's resource fork. Since it is intended to work only on 
source code files, the segment of the program that effects a file's 
resource fork must first check to see if the file is of type ‘TEXT’ 
and has a creator of ‘MPS ‘ (the MPW signature). If this is so, 
ChangeTextRes will proceed to change the file's resource fork. 
Below is the segment of code that accomplishes this task. 


if (fnderInfo.fdType = ‘TEXT’) and 
(fnderInfo.fdCreator = 'MPS ') then begin 
if gResDelete then begin 
anOSError := OpenRF(filename, vRefNum, 
ResRef Num); 
anOSError := SetEOF(ResRefNum, 0); 
anOSError := FSClose(ResRefNum); 


end; 
result := IEFAccess(filename, F_STabInfo, 
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gTabS ize); 
result := IEFAccess(filename, F_SFontInfo, 
arg); 

end 


The global variable gResDelete is affected by the -d option. 
If the -d option is present on the command line, gResDelete is set 
to true, otherwise it is set to false. Only when gResDelete is true 
will all the resources be deleted. 

An MPW file’s font, font size and tab setting are modified 
with calls to the IEFAccess function. This function is defined in 
the IntEnv unit. There are three parameters to IEFAccess. The 
firstis the filename on which the routine is to operate. The second 
parameter defines which operation to perform, and the third 
provides a means of passing data to and receiving results from the 
IEFAccess routine. 

Our first call to IEFAccess sets the tab setting of a file. The 
predefined constant F_STabInfo informs IEFAccess to set the 
tab of the specified file and the third parameter specifies the 
desired tab setting. The second call to IEFAccess sets the font 
and font size. The second parameter of IEFAccess is set to the 
predefined constant F_SFontInfo. Apple has inadvertently 
documented that the third parameter, in this case, is a pointer to 
the new font and font size. This is not the case, rather, the upper 
word of this long integer is the font number and the lower word 
contains the font size. Both F_STabInfo and F. SFontInfo are 
defined in the IntEnv unit. 


Spinning the Beach Ball Cursor 

MPW Tools are, by convention, supposed to provide visual 
feedback to the user by displaying and spinning a cursor. By 
default, this cursor is the MPW beach ball cursor but may be any 
other cursor the programmer defines. Spinning cursors have a 
resource type of 'acur' and may be created with MPW'sresource 
editor and/or resource compiler. See the appendix “Program- 
ming for the Shell Environment" in the MPW Pascal Reference 
Manual or Appendix D of the TML Pascal II Language Refer- 
ence for more details on creating and using such resources. 

All the routines related to the operation of the cursor by an 
MPW Tool are contained in the CursorCu unit. Only two 
routines in this file are required by most tools: InitCursorCtl and 
RotateCursor. 

For a tool to rotate the cursor, it must first call InitCursorCu. 
This routine has just one parameter which is a handle to an ‘acur’ 
resource. If this parameter is nil, then the cursor defaults to 
MPW's spinning beach ball cursor. Call this routine very early 
in the program to prevent fragmentation of the heap. 

Initializing the spinning cursor does not in itself cause the 
cursor to spin. The MPW Tool must manually spin the cursor 
itself. This may seem to be an inconvenience, but it is actually 
to your advantage. For example, a user can track progress of the 
MPW Linker by watching which way the beach ball rotates. The 
linker has three phases, each change in phase is accompanied by 
a change in direction of rotation of the cursor. 

Torotate the cursor, call RotateCursor(value) where value is 
some integer or long integer. Each time this procedure is called, 
value is added to an internal counter. When this counter is an 
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even increment of 32, the beach ball is rotated. If value is 
positive, the cursor is rotated in the clockwise direction. If value 
is negative, the cursor is rotated in the counter-clockwise direc- 
tion. It is important to call RotateCursor on a frequent basis. It 
is usually best to place this procedure call in the main loop of the 
program. 


Softwarelnterrupts 

MPW Tools should be capable of responding to software 
interrupts known as signals. Currently, only one type of signal 
exists and that is the command-period (.). Signals have the 
capability of pre-empting a tool or any other MPW command. 
Tools will automatically respond to a signal but it may be 
necessary at times to prevent a signal from pre-empting a tool. 
Several routines in the Signal unitallow a tool to control the effect 
a signal may have on it. ChangeTextRes does not in any way 
attempt to control a signal’s effect. 

The default actions taken by a tool in response to a signal 
are to close all open files, execute any installed exit procedures, 
and terminate the program. See the appendix “Programming for 
the Shell Environment" in the MPW Pascal Reference Manual or 
Appendix D of the TML Pascal Il Language Reference for more 
details on how to install exit procedures. Also refer to these 
manuals for information on how to prevent or delay the effects of 
signals on MPW Tools. 


Returning Status Results 

There are basically three different conditions that cause 
ChangeTextRes to terminate. The firstis normal termination and 
arises when ChangeTextRes has successfully completed proc- 
essing its data. There are two abnormal termination conditions. 
One is due to invalid syntax of command line parameters and the 
other to the inability for the tool to successfully complete its task. 
Inany case, whena tool returns control to the MPW Shell, it must 
inform the Shell of its termination condition. This is done by 
returning a status code. 

Defined in the IntEnv unit is the procedure IEExit. This 
procedure has one parameter of type LongInt. When a tool is to 
terminate, either normally or abnormally, it should call IEExit. 
Note that IEExit actually terminates the program. The value of 
its parameter is returned to the MPW Shellasastatus code, which 
by convention, is zero to signify normal completion and non-zero 
to indicate abnormal termination. ChangeTextRes returns 1 to 
indicate a syntax error and 2 to indicate other errors. 


Further Reading 

This article has addressed many of the issues involved in 
writing MPW Tools, but there still remains a significant amount 
of potential yet to be realized. The chapter "Writing an MPW 
Tool" of the Macintosh Programmer' s Workshop Reference 
discusses all the issues of writing MPW Tools, and does so in 
much greater detail than presented here. The chapter "Building 
an Application, a Desk Accessory, or an MPW Tool” of the same 
reference describes the mechanics of building a tool, but this 
knowledge is not necessary if you are using the TML Project 
Manager. 
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Chapter 8 of the TML Pascal II User' s Guide shows how to 
write MPW Tools as does Programming with Macintosh 
Programmer' s Workshop, by Joel West. This second book is 
highly recommended for any MPW user. Appendix D of the 
TML Pascal II Language Reference and appendix titled “Pro- 
gramming for the Shell Environment" of the MPW Pascal 
Reference Manual give complete descriptions of the interface 
files required to create MPW Tools. 


Next Month 
Next month, we will developa graphical interface, called the 
Commando interface, for the ChangeTextRes tool. We will also 
show how to add or modify Commando interfaces to other 
existing MPW Tools. 


program ChangeTextRes; 
(  ChangeTextRes.p 


An MPW Tool to delete resource fork of MPW 

text files and rewrite the resource fork 

to specify a desired tab setting, font, 

and font size. 

(c) TML Systems, Inc., 1988 

All rights reserved. Publication rights granted to 
MacTutor. 


uses MemTypes, QuickDraw, OSIntf, ToolIntf, 
PackIntf, PasLibIntf, 


( required for MPW Tools ) 
CursorCtl, IntEnv; 


var 
ResRefNum : integer; 
( reference number for resource fork of a given file } 
filename : Str255; 
aStringPtr : StringPtr; 
( reference number for default drive ) 
vRef Num : integer; 
( Finder information for a given file ) 
fnderInfo : FInfo; 
( result from Mac ROM file 1/0 calls ) 
anOSError : 05Егг; 
( passed to ІЕҒАссе55 specifies font and font size ) 
arg : LongInt; 
( result from IEFAccess calls } 
result : LongInt; 
i : integer; 


( Font number of specified font as returned bu GetFNum ) 


gFont : integer; 
gFontSize : LongInt; 
gTabSize | : LongInt; ( tab setting ) 


( delete all of file’s resources? ) 
gResDelete : boolean; 


function UpperCase(str: Str255): Str255; 
( Convert an alpanumeric string to all 
uppercase characters. 


for i := 1 to length(str) do 
if (str[i]) >= ʻa’) and 
Cstrli] <= 'z^) then 
str[i] := chrCord(strlil) - 32); 
UpperCase := str; 
end; 
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procedure SuntaxError(err: integer; 


( 


msg: Str255); 
Display the appropriate syntax error and 
then exit from the program. Return a 
status value of 1 indicating an early 
termination of program. 


begin 


case err of 


1: writelnC'8 “ msg, ' is an invalid option’); 


: writelnC'* missing font’); 
writelnC'* missing font size’); 
writelnC'8 missing tab setting’); 


со Ко Ol +. CO PO 


writelnC'* the - character must be 
accompanied by an option’); 


WO 


: begin 


writelnC'* Usage - ChangeTextRes [name..] 


writelnC* -f fontname "8 set 
font of files to fontname’); 
writelnC' -s fontsize "8 set 
font size of files to fontsize’); 
writelnC' -t tabs 8 set 
tab setting to tabs’); 
end; 
otherwise 
writelnC'fatal error 8”, err); 
end; 
IEExitC12); ( return error status of 1) 


end; 


procedure HandleQption(opt: Str255; 


( 


) 


var ergIndex: integer); 


set the appropriate global flag for each 
command line option encountered on the 
command line. If an invalid 

Option is found, give an error message and 
exit from the program. If the option 
requires an additional command line 
parameter (e.g. -f Monaco), then retrieve 
the option(s) needed and increment the 
argindex counter appropriately. 


var 


NumString, str : Str255; 


begin 


str := UpperCase(opt); 
Delete(str, 1, 1); 
(delete the '-^ character) 
if str = ‘F’ then begin ( set font ) 
argIndex := argIndex + 1; 
if argIndex < argc then begin 
GetFNumCargv^ [argIndex]^, gFont); 
if gFont < 0 then 
eyntaxError(5, argv^l[argIndex]^); 
end 
else SyntaxError(2, ‘’); 
end 
else if str = 'S' then begin 
( set font size ) 
argindex := argIndex + 1; 
if argIndex < argc then begin 


StringToNumCargv^ largIndex]^, gFontSize); 


if (gFontSize <= 0) or 
(gFontSize >= 128) then begin 
NumToStringCgFontSize, NumString); 
syntaxError(6, NumString); 
end; 
end 
else SyntaxError(3, ‘’); 
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writelnC'8 “ msg, * is an invalid font’); 
writelnC'8 °, msg,’ is an invalid font size’); 
writelnC'? “ msg, ' is an invalid tab size’); 


end 

else if str = ‘T’ then begin ( set tab ) 
argIndex := argIndex + 1; 
if argIndex < argc then begin 


StringToNumCargv* [argIndex]*, gTabSize); 


if (gTabSize <= 0) or 
(gTebSize >= 25) then begin 


NumToStringCgFontSize, NumString); 


SyntaxError(7, NumString); 
end; 
end 
else SyntaxError(4, ‘’); 
end 
else if str = 'D' then 
gResDelete := true 
else SyntaxError(1, str); 
end; 


procedure SkipOptionCopt: Str255; 
var argIndex: integer); 


This routine is called only after the 
command line parameters have already been 
scanned once using HandleQption. Тһе 
purpose of this routine is to properly 
increment argIndex according to the 
appropriate command line options. 


) 
var 
str: Str255; 
begin 
str := UpperCase(Copt2; 
Delete(str, 1, 1); 
(delete the '-^ character) 
if str = ‘F’ then ( set font ) 
argIndex := argIndex + 1 
else if str = ‘S’ then ( set font size ) 
argIndex := argIndex + 1 
else if str = ‘T’ then ( set tab size ) 
argIndex := argIndex + 1 
else if str = ‘D’ then 
( nothing ) 
end; 
procedure ReadCommandL ine; 
var 
argVIndex : integer; 
arg : $tr255; 
begin 


if argc = 1 then SuntaxError(9, 77); 
argVIndex := 1; 
while argVIndex < argc do begin 
arg := argv^[argVIndex]^; 
if length(arg) © Ø then 
if arg[1] = -” then 
if lengthCarg) > 1 then 
HandleOptionCarg, argVIndex) 
else SyntaxError(8, ‘’); 
argVIndex := argVIndex + 1; 
end; ( while ) 
end; 


procedure ReportErrorCerror: integer; 
filename: Str255); 


Generate the appropriate error message 
then exit from the program. Return a 
status value indicating early termination 
from the program. 


begin 
if error = 0 then 
exit(ReportError); 
write(diagnostic, “ERROR! 7): 
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case error of 
-35: writeln(diagnostic, filename, 
* volume does not exist’); 
-36: writelnCdiagnostic, filename, 
‘ 10 Error’); 
-37: writelnCdiagnostic, filename, 
“із a bad filename or volume name’); 
-42: writelnCdiagnostic, 
‘Too many files open’); 
-43: writelnCdiagnostic, filename, , 
f not found’); 
-45: writelnCdiagnostic, filename, 
' is locked’); 
-46: writelnCdiagnostic, filename, 
' is locked by a software flag’); 
-47: writeln(diagnostic, filename, 
‘ is busy; one or more files are open’); 
-53: writelnCdiagnostic, filename, 
“ volume not on-line’); 
-54: writelnCdiagnostic, filename, 
‘ cannot be opened for writing, file is 
locked’); 
-61: writelntdiagnostic, filename, 
' Read/write permission doesn’ ’t allow writing’); 
otherwise 
writelnCdiagnostic, ‘OS error 8”, 
error, ' has occurred.’); 
writelnCdiagnostic,^ Reference Inside 


Macintosh pp. 111:205-209 for further details’); 


end; 
IEExit(2); 
end; 


begin (main program) 
( make first stmt toavoid heap fragmentation } 
InitCursorCtl(ni1); 
InitFonts; (so we can read in font names) 


( so we read in JUST the font names! ) 
SetResLoad(false); 


( Set default values ) 
gResDelete := false; 
gFont := 4; 

gFontSize := 9; 
gfebSize := 3; 
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end. (nain program) 


ReadCommandL ine; 
arg := gFont; 
arg := BSLCarg, 16); 


erg arg * gFontSize; 

ап05Еггог := GetVolCaStringPtr, vRefNum); 

if anOSError © 0 then 
ReportErrorCanOSError, aStringPtr^2); 

і := 1; 

while i < argc do begin 


( Make cursor rotate each time through loop } 


RotateCursor (32); 
filename := ergv^[il^; 
if length(filename) = r then begin 
і = it 1 
cycle; 
end; 
if filename[1] = '-' then 
SkipOptionCfilename, i) 
else begin ( valid filename ) 
anOSError := GetFInfoCfilename, vRefNum, fnderInfo); 
if anOSError € 0 then begin 
ReportErrorCanOSError, filename); 
cycle; 
end 
else begin (file exists ) 
if (fnderInfo.fdTygpe = ‘TEXT’) and 
(fnderInfo.fdCreator = ‘MPS ') 
then begin 
if gResDelete then begin 
anOSError :- OpenRF(filename, vRefNum, ResRefNum); 
anOSError := SetEOF(ResRefNum, 0); 


2 


anOSError : FSClose(ResRefNum); 
end; 
result := IEFAccess(filename, F_STabInfo, gTabSize); 


result := IEFAccess(filename, F_SFontInfo, arg); 
end 
else 

writelnC'WARNING! 7, filename, ' is not an MPW text 


file, resources not deleted’); 


end; (file exists ) 
end; ( valid filename ) 
i := j + Í; 
end; ( while i < argc } 
writeln; 
SetResLoad( true); p 
IEExit(@); ( Normal status return ) Se} 
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Advanced Mac ing 


Re-sizing with Window Corners 


I suppose you've probably heard of the new Open Look 
interface for Unix. (Not so new anymore, actually!) The thing 
looks pretty familiar— windows, scroll bars, menus. Everything 
has some kind of a twist on it, though. The menus are all pop-ups; 
the scroll bars include the up and down arrows as part of the 
indicator; and the windows can be re-sized from any corner, not 
just the lower right corner. 

That’s an interesting idea, re-sizing from any corner. I 
wonder if you could do that on the Mac... I held a long argument 
with myself on that topic, and the affirmative finally won. You 
can do it on the Mac; here’s one way. 

Before I get started, let me thank Tom Leonard, who encour- 
aged me, and Don Melton and Mike Ritter, whose article in the 
April MacTutor inspired me. 


THE WINDOW 

The first half of the problem is to draw the window with 
appropriate grow brackets in the corners, and to have it return the 
"wInGrow" message when the user clicks in one of them. This 
is done in a window definition procedure, or WDEF. 

WDEF's have been pretty well covered in MacTutor; I refer 
you to the Window Manager chapter of Inside Macintosh, and to 
Melton and Ritter’s WDEF discussed in their April article and 
published in May. 

By the way, an earlier version used WDEF 0 to do most of 
the work. Apple, however, has declared its intention to remove 
WDEF 0 from the System file (it hasn't done it yet). So I figured 
I had better do it myself. One thing led to another, and this 
program now supports zoom windows on the old 64K ROM. 


THE PATCH 

If all I did was insert the WDEF, I'd get a nice looking 
window with some funny behavior (try it! nothing bad will 
happen). Ineed to make the Window Manager respond appropri- 
ately to mouse downs in a grow bracket. 

So taking the hint from Melton and Ritter, I replaced the 
GrowWindow and SizeWindow routines. And while I was at it, 
I made my new "sizethewindow" routine a replacement for 
ZoomWindow as well, and added a replacement for TrackBox, 
so I could zoom windows as well as grow them. 


BLOW-BY-BLOW 
The program is contained in the file “Corners.p”, the re- 
placement routines in the unit "Patches.p", and the WDEF in the 
file “WDEF.p” (Okay, so I lack imagination!). There's another 
unit “Common.p” that at one time was substantial but now has 
only some minor type and constant declarations. The resource 
source file is "Corners.r". 
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Pascal Corners 


untitled =): 


When the user clicks in one of the corner brackets, the 
program calls FindWindow, which in turn calls the WDEF. The 
WDEF returns wInGrow if the click was close to any of the 
corners. Simple so far. FindWindow tells the program the click 
was in the grow box, and the program calls the Patches routine 
"growthewindow" in place of the ROM's GrowWindow. 

Growthewindow has a lot of work to do. It must track the 
mouse, and draw a gray outline of the re-sized window as it does 
so. When the mouse is released, it must return not just the new 
dimensions of the window but the new location as well. 

Growthewindow doesn'tactually draw the gray outline; that 
is done by the WDEF. But it must tell the WDEF the rectangle 
to use when drawing. The basic method of computing this 
rectangle is (1) find the fixed corner of the window (the one 
opposite the corner being dragged), which I call the “pivot”; (2) 
track the mouse in a loop, each time getting the current mouse 
position; (3) use the wonderful Toolbox routine Pt2Rect to 
convert the mouse position and the pivot into a rectangle; and (4) 
call the WDEF to draw the gray outline from that rectangle. 

That sounds simple but there are a lot of small things that 
cloud the picture. For example, the old gray outline must be 
erased before the new is drawn. And the mouse will rarely start 
out at the corner of the portrect, so a correction must be applied. 
Andthen there are various constraints on the rectangle, e.g., those 
imposed by the SizeRect parameter. Also, the rectangle must be 
in global coordinates. 

Whenall this is done, and the user releases the mouse button, 
the routine must return the window's new size and location. 
What could be easier than just returning the last rectangle? 

Now we're back to the Corners program. It has the new 
portrect, in global coordinates, as returned by growthewindow. 
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It calls another Patches routine, “sizethewindow”, which makes 
the actual changes in the window. 

Sizethewindow does more than just re-size the window. 
Since the top left corner may have moved, the window must be 
moved as well. My first version of this routine called MoveW- 
indow and SizeWindow but this resulted in two updates. Nesting 
the calls within ShowHide calls solved that but... I wanted 
something that would look just as smooth as the normal grow. 
Zoom Window worked but limited the program to machines with 
the new ROM. Finally I discovered the QD routine MovePortTo, 
which does not update the screen! It is amazing what you can 
find, overlooked for years, in the QD chapter! 

When I made that discovery, I realized that my sizethewin- 
dow routine could easily pinch-hit for Zoom Window, giving me 
zoom windows on the old ROM. So for our next adventure, we 
will ask the user to click on the zoom box... 


BLOWS AGAINST THE ZOOM BOX 

Once again, the program calls FindWindow, which calls the 
WDEF, which returns wInZoomIn (I might note here that the 
WDEF could return anything I want, since this is all done 
privately). The program than calls the Patches routine “‘trackthe- 
box". 

Trackthebox is kinda rough; I think it could be slimmed 
down but why bother? The time it takes is entirely determined by 
the user. Anyway, it goes into a loop, getting the mouse location, 
calling the WDEF to find out where that is, and calling the WDEF 
to highlight the zoom box if the mouse had just moved either in 
orout. When the button is released, the routine returns true if the 
mouse is still in the zoom box, false otherwise. 

Now the program gets busy. First, note that one field of the 
record whose handle is stored in the refcon field of the window 
recordis called "zoomrect". Suggestive, huh? It gets the portrect 
of the window and compares it with a full screen portrect (this is 
done in global coordinates, of course). If the window is notat full 
Screen, then its current portrect is saved in the zoomrect field, and 
sizethewindow zooms it to full screen. If it is at full screen, then 
the zoomrect is used to size it back down. 


PUTTING IT TOGETHER 

To add four-cornered windows to your program, add the 
Patches unit to your uses clause and the WDEF to the resource 
file. Then change the type of your windows from zoomDocProc 
or whatever to 800. Finally, change calls to GrowWindow and 
SizeWindow to “growthewindow” and “sizethewindow” (this 
will require more than just a name change but not much more). 

If you want to support zooming, you'll have to hack a little 
further. Let the description above be your guide. | 


Listing: Comnon.p 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ +) 


unit Common; 
(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


interface 
( ЖЖЖЖАЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖ 


keu codes: 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У) 
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const 
enterkeu = 3; 
backspace = 8; 
tabkey = 9; 
returnkey = 13; 
clearkey = 21; 
lef tarrow = 28; 
rightarrow = 29; 
uparrow = 30; 
downarrow = 31; 
per iodkey = 46; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Dialog items: 
Xx xocooocoooooooeceoorooooooboooooceoooooooooboooooooocooooooocoeg) 
themask = 3; 
(ХЖЖЖЖЖЖЖЖЖХЖЖЖЖЖХЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖХЖ 


Low-memoru globals: 
ЖЖЖЖАЖЖЖХАЖАЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


applscratch = $A78; 
bootdrive = $210; 
curappname = $910; 
curdirstore = $398; 
currentad = $904; 
f indername = $2E0; 
fsfcblen = $3F6; 
grayrgn = $9EE; 
iaznotify = $33C; 
mbarhe ight = $BAA; 
menuf lash = $424; 
resload = $A5E; 
rom85 - $28E; 
sfsavedisk - $214; 
sysmap - $458; 
windowlist - $9D6; 


(ЖЖЖЖЖАЖАЖЖЖЖЖЖЖЖЖАЖАЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Standard tupes: 
МА KAKA AAA ROIG IO EEK ERE EE EKER KX ) 


type 


logical = boolean; 

long = longint; 

shortpointer = “integer; 

longpointer = “long; 
(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖУ 


end. 
(KK RK KKK KKK KO KKK KK KK KKK) 


Listing: Corners.p 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Corners.p 


Shell program for four-cornered windows. 


(c) 1988, bu Clifford Storu & Attic Software 


ЖЖЖЖЖАЖХЖЖЖЖЖЖАЖАЖЖЖЖЖХЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖХ) 


program Corners; 
(RRR KK KKK HAKKAR KAKA KKK KK KKK RK KKK KKK KEK KKK K KK KAKA KK KKK) 


uses memtypes, quickdraw, osintf, toolintf, Common, 
Patches; 
(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 

Program constants: 
ЖЖЖЖЖЖАЖЖЖАЖЖЖЖХЖЖЖЖЖЖЖЖХАЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


const 


applenum = 1001; 
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aboutitem 


" 
— У 
me 


atticitem = 2; 
filenum = 1002; 
newitem = 1; 
closeitem = 2; 
quititem = 4; 
editnum = 1003; 
undoitem = 1; 
cutitem = 3; 
copyitem = 4; 
pasteitem = 15; 
clearitem = 6; 
windownum = 1001; 
scrollnum - 1001; 
hoffset - 32; 
voffset - 20; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Program tupes: 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЕЖЖЖЖЖЖЖЖЖЖЖЖ 


tupe 

wrecord = record 
window : WindowPtr; 
zoomrect : Rect; 
hscrol] : ControlHandle; 
vscroll : ControlHandle; 
disprect : Rect; 

end; 

wpointer = “wrecord; 

whandle = ^wpointer; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Program variables: 
X Ico OOOOOOOOOQOQOOoIolooloooopoooooooocooooooooooooocooonopooooooocooocoor) 


var 


APPLEMENU : MenuHandle; 
F ILEMENU : MenuHandle; 
EDITMENU : MenuHandle; : 
MOUSEREGION : RgnHandle; 
SCREENREG ION : RgnHandle; 
MENUHE IGHT integer; 
DRAGRECT : Rect; 
GROWRECT : Rect; 
SCREENRECT : Rect; 
COLUMNS integer; 
ROWS : integer; 
WINDOWCOUNT integer; 
DONE : logical; 
JEVENT : logical; 
MAINEVENT : EventRecord; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У 


procedure .datainit; external; 
(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖУ 


($R-) 
($SC+) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖУ 
procedure panic; 
begin 
ExitToShe11; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У) 
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procedure initmac; 
begin 

MaxApp 1Zone; 
InitGraf (@8thePort); 
InitFonts; 
InitWindows; 
InitCursor ; 
InitMenus; 
TEInit; 
InitDialogs(@panic); 


UnloadSeg(@_datainit); 
end; 


(ЖЖЖЖЖХЖЖХЖХЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖХ)) 
procedure setupmenus; 
begin 
APPLEMENU := GetMenuCapplenum); 
AddResMenuCAPPLEMENU, ‘DRVR’); 
InsertMenuCAPPLEMENU, 0); 


FILEMENU := GetMenu(filenum); 
InsertMenuCF ILEMENU, 0); 


EDITMENU := GetMenuCeditnum); 
InsertMenuCEDITMENU, 0); 


DrawMenuBar ; 
end; 


(ЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖ 
initglobals 


Here’s where I initialize all the global variables. 

DRAGRECT is an argument to DragWindow; GROWRECT is an 

argument to “growthewindow” Cin the Patches unit); 

SCREENRECT is used in zooming Cit’s the portrect of a full- 
screen window); and ROWS and COLUMNS are used to stack the 
windows on the screen. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖ 


procedure initglobals; 


var 
index integer; 
theshort : shortpointer; 
begin 
for index := 1 to 10 do 
MoreMasters; 


if BitTst(Ptr(rom85), Ø) then begin 

MENUHEIGHT := 20; 

JEVENT := false; 
end else begin 

theshort := shortpointer(mbarheight); 

MENUHEIGHT := theshort^; 

JEVENT := (NGetTrapAddress($4860, ToolTrap) 

O NGetTrapAddress($A89F, ToolTrap)); 

end; 


wlth screenBits.bounds do begin 
SetRect(DRAGRECT, left + 5, top + MENUHEIGHT + 5, 
right - 5, bottom - 25); 
SetRect(GROWRECT, 160, 100, right - left - 10, 
bottom - top - MENUHEIGHT - 10); 
SetRect(SCREENRECT, left + 5, top + MENUHEIGHT + 25, 
right - 5, bottom - 55; 
COLUMNS := 1 + ((right - left - 330) div hoffset); 
ROWS := 1 + (bottom - top - MENUHEIGHT - 230) div 
voffset); 
WINDOWCOUNT := Ø; 
end; 


DONE := false; 
end; 
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(ЖЖЖЖЖХЖХЖХЖЖЖАЖХАЖАХЖХЖАЖЖАЖХЖХЖЖЖЖХЖХЖЖЖЖЖХЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
clickapplemenu 


This may not be new to you but it is to me! Instead of 
using an alert for the “About...” box, I’m using a picture. 
First I open a new GrafPort, then draw the picture in its 
center. Note that I must re-draw the windows after the user 
dismisses the screen, using PaintBehind. 
ЖЖАЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖАЖХЖЖЖЖАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖ ) 


procedure clickapplemenu(theitem:: integer); 


var 
itemname : Str255; 
sevedport : GrefPtr; 
dummy : integer; 
newport : GrafPort; 
thepicture : PicHandle; 
therect : Rect; 

begin 


if theitem > 3 then begin 
GetItemCAPPLEMENU, theitem, itemname); 
GetPor tCsavedpor t); 
dummy := OpenDeskAccCitemname); 
SetPortCsavedpor і); 

end else if theitem < 3 then begin 


InitCursor; 

GetPort(savedport); 
OpenPor tC@newpor t); 
SetPor tC@newpor t ); 


thepicture :- PicHandle(GetResource( ‘PICT’, 
1000 + theitem)); 

with thepicture^^.picFrame do 

SetRect(therect, 0, Ø, right - left, bottom - top); 
with screenBits.bounds, therect.botright do 

OffsetRect(therect, (right - left - n2 div 2, 

(bottom - top - v) div 3); 

DrewPictureCthepicture, therect); 


repeat until Button; 


ClosePor t(@newpor t); 

EnableItemCEDITMENU, 0); 

DrawMenuBar ; 

PaintBehind(WindowPeekCFrontWindow), 
RgnHandleClongpointer(Cgrayrgn)*^ 2); 


SetPort(savedport); 
FlushEventsCeveryEvent, 0); 


end; 
end; 


( ЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
placewindow 


This routine cost me $40.00 Cit’s the only thing I got out 


of “Macintosh Revealed”). 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У 


procedure placewindow(thewindow : WindowPtr); 


маг 
left : integer; 
top : integer; 
begin 


left := 5 + hoffset * (WINDOWCOUNT mod COLUMNS); 
top := 5 + MENUHEIGHT 
+ voffset * (1 + CWINDOWCOUNT mod ROWS)); 


MoveWindowCthewindow, left, top, true); 
end; 


( ЖЖЖЖЖЖЖЖЖЖАЖАЖЖЖЖАЖЖЖЖЖЖАЖЖАЖЖАЖЖЖЖЖАЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖ ) 
procedure wsize(thewindow : whandle); 
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var 
thewidth integer ; 
theheight integer; 
begin 


HLock(CHandle( thew indow)); 
with thewindow^^ do begin 


thewidth := window* .portRect right; 
theheight := window* .portRect.bottom; 


HideControlChscrol1); 
HideControl(vscrol1); 


MoveControlCvscroll, thewidth - 15, -1); 
SizeControl(vscroll, 16, theheight - 13); 


MoveControl(hscroll, 15, theheight - 15); 
SizeControlChscroll, thewidth - 29, 16); 


disprect := window^.portRect; 
InsetRect(disprect, 10, 10); 
OffsetRect(disprect, -8, -8); 


ShowControlChscrol1); 
ShowControl(vscroll); 


end; 
HUnlock(Handle(thewindow)); 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 
procedure donew; 
label 
100; 
var 
thehandle 
thew indow 
begin 
thehandle := whandleCNewHandle(Csizeof (wrecord22); 
if thehandle = nil then 
goto 100; 


: whandle; 
: WindowPtr; 


HLockCHandle(thehandle2)2; 
with thehandle^^ do begin 


window :- GetNewWindow(windownum, nil, WindowPtr(- 
125; 
if window = nil then begin 
DisposHandleCHandleCthehandle)); 
goto 100; 
end; 
SetWRef ConCwindow, long(thehandle)); 


zoomrect := SCREENRECT; 


hscroll := GetNewControlCscrollnum, window); 
if hscroll = nil then begin 
DisposeW indow(window); 
DisposHandleCHandle(Cthehandle)); 


goto 100; 
end; 
vscroll := GetNewControlCscrollnum, window); 


| Af vscroll = nil then begin 
DisposeControl(hscro11); 
DisposeWindow(window2; 
DisposHandleCHandleCthehandle)2); 
goto 100; 
end; 


placewindowCwindow); 


wSize(thehandle); 
ShowWindow(window); 
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WINDOWCOUNT := WINDOWCOUNT + 1; 
end; 
HUnlock(Handle(thehandle)); 
100: end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖ У 


procedure doclose(thepeek : WindowPeek); 
var 
thehandle : whandle; 
begin 


if thepeek^.windowkind < 0 then 
CloseDeskAccCthepeek^ .windowk ind) 

else begin 
thehandle := whandleCthepeek^ .refCon); 
DisposeControlCthehandle^*^.hscro112; 
DisposeControlCthehandle^^.vscrol1); 
DisposeWindow(WindowPtr(thepeek )); 
DisposHandleCHandle(Cthehandle2); 
WINDOWCOUNT := WINDOWCOUNT - 1; 

end, 

end; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 


ргосейцге clickfilemenu(itemchoice : integer); 
var 
dummy logical; 
begin 
case itemchoice of 
newitem : donew; 
closeitem : docloseCWindowPeek(FrontWindow)); 
quititem : DONE := true; 
end; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ') 
procedure checkmenu(thewindow : WindowPeek); 
begin 
DisableItemCEDITMENU, 0); 


if thewindow = nil then 
Disableltem(FILEMENU, closeitem) 

else begin 
if thewindow^.windowkind € userKind then 

EnableItemCEDITMENU, 0); 

EnableItemCFILEMENU, closeitem); 

епа; 

end; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 


procedure clickinmenu; 
var 
choice 
begin 
checkmenuCWindowPeek(FrontWindow 22; 
choice := MenuSelect(MAINEVENT . where); 


: long; 


case HiWord(choice) of 


applenum : clickapplemenuCLoWord(choice)); 
f ilenum : Clickf ilemenu(LoWordCchoice22; 
editnum if not SystemEditCLoWord(choice) - 1) 
then; 
end; 
HiliteMenu(d); 
end; 


(YXXXKXXKXXXXXXXXXXXXXXXXXKXXXXXXXXXXXXXXXXXXKKXXXXKXKKXXXXXXKX 
clickingrow 
This is just like the usual grow routine, except that I’m 
calling the Patches routines “growthewindow” and 
“sizethewindow”. These behave like GrowWindow and 
SizeWindow, but in the four-cornered context. 
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KKK KKK KKK KEK KKK KK KKK EK KKK KKK KAKA A `) 


procedure clickingrowCthewindow : WindowPtr); 
var 
newrect 
begin 


: Rect; 


і? growthewindowCthewindow, MAINEVENT .where, 
GROWRECT, newrect) then begin 
sizethewindowCthewindow, newrect); 
ws izeCwhandle(GetWRef Con( thewindow))); 
end; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ') 
procedure clickingoawau(thewindow : WindowPtr); 
begin 
if TrackGoAway(thewindow, MAINEVENT.where) then 
doclose(WindowPeek(thewindow)); 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
clickinzoom 


Custom zooming - this will work on any ROM. “trackthebox’ 
performs exactly like TrackBox; I wrote it so I could track 
clicks in the zoom box regardless of ROM version. The 


actual zooming uses "sizethewindow^, which I already have 
for growing windows. 


Each window has a field called "zoomrect". If I’m zooming 
to full screen, I save the old portRect in zoomrect first. 
If I’m already at full screen and I’m zooming back, I use 
the save zoomrect as the target portRect. Note, though, 
that zoomrect must be in global coordinates. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ УУ 


procedure clickinzoom(thewindow : WindowPtr); 


var 
thehandle : whandle; 
therect : Rect; 
begin 


if tracktheboxCthewindow) then begin 
thehandle := whandleCGetWRef ConCthewindow2); 
therect := thewindow^ .portRect; 
EraseRect(Ctherect 2; 


LocalToGlobal(Ctherect . toplef t2; 
LocalToGlobal(therect .botright); 


if EqualRect(therect, SCREENRECT) then 


therect := thehandle^^.zoomrect 

else begin 
thehandle^^.zoomrect := therect; 
therect := SCREENRECT; 

end; 

sizethewindowCthewindow, therect); 

wsizeCthehandle?); 

end; 
end; 


(YXYXXXXXXXXXXXXXXXXXXXXXXXXKXXKXXXXXKXKXKXXXXKXXXXXKXKXKXKXXXKE) 
procedure aclick; 


var 
location integer; 
thewindow : WindowPtr; 
begin 
location := FindWindow(MAINEVENT.where, thewindow); 


case location of 
inDesk : SysBeep(1); 
inMenuBar : clickinmenu; 
inSysWindow: SystemClickCMAINEVENT, thewindow); 
inContent : SelectWindow( thewindow); 
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inDreg : DragWindow(thewindow, MAINEVENT.where, 
DRAGRECT); 


inGrow  : clickingrow(thewindow); 
inGoAway : clickingoaway(thewindow); 
inZoomIn : clickinzoomCthewindow); 
end; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 
procedure akeu; 


var 
charcode integer; 
choice : long; 
begin 


if BitAndCMAINEVENT.modifiers, cmdKey) © then begin 
charcode := BitAndCMAINEVENT.message, charCodeMask); 
checkmenuCW indowPeek(FrontWindow)); 
choice := MenuKey(chr(charcode)); 
if choice o Ø then begin 


case HiWordCchoice) of 


applenum  : clickapplemenuCLoWord(choice)); 
f ilenum : clickfilemenuCLoWordCchoice2); 
editnum if not SystemEditCLoWord(choice) - 
1) then; 
; end; 
HiliteMenu(0); 
end; 
end; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖАЖЖЖХЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 
procedure anactivate(thewindow : WindowPtr); 
begin 
oetPort(thewindow); 
DrawGrowIcon(thewindow); 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 
procedure anupdate(thewindow : WindowPtr); 
var 
savedport 
begin 
GetPort(savedport); 
SetPortCthewindow); 


: CrafPtr; 


Beg inUpdate( thewindow); 


ClipRectCthewindow^ .portRect); 
EraseRectCthewindow^ .portRect); 
DrawGrowIcon( thew indow); 
DrewControlsCthewindow); 


EndUpdate( thewindow); 


SetPort(savedport); 
end; 


(ooooooooooooooooooooooooorororooroooooooooooooooooooooooooooecer) 


procedure mainloop; 
var 
dummy 
begin 
repeat 


if JEVENT then 
dummy := waitnexteventCeveryEvent, MAINEVENT, 
GetCaretTime, nil) 
else begin 
SystemTask; 
. dummy := GetNextEventCeveryEvent, MAINEVENT); 
end; 


logical; 
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1f dummy then begin 
case MAINEVENT. what of 


mouseDown : aclick; 
keyDown : akey; 
autoKey : akey; 
activateEvt : 
anactivateCWindowPtr(CMA INEVENT .message )); 
updateEvt 
anupdate(WindowPtr(CMAINEVENT .message )); 
end; 


end; 


until DONE; 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ 
procedure shutdown; 


var 
the long longpo inter ; 
thepeek : WindowPeek; 
begin 


thelong := longpointerCwindowlist); 


thepeek := WindowPeekCthelong^); 
while thepeek © nil do begin 
doc lose( thepeek ); 
thepeek := thepeek* .nextwindow; 
end; 
end; 
(ЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ Ж 
begin 
initmac; 
setupmenus; 
initglobals; 
mainloop; 
shutdown; 
end. 


Qoooocoooooooooeloeoroorooooocolooorcorooooooloooroooocioecoooooocoooboeee) 


Listing: Patches.p 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Patches.p 

ROM replacements for four-cornered windows. 

(c) 1988, bu Clifford Storu & Attic Software 
ЖЖЖЖЖАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


unit Patches; 
Qooboocoocoocoooecoooococoooocoopbooobdoooecooooecooocpeooooooooooooeoeexe) 


interface 
QoeoeoooecooeocoooeooocoooboocooocooocooooooocoeoobooeoooooÁpbooeooeoec) 


uses memtypes, quickdraw, osintf, toolintf, Common; 
Qooo)ooooocoroooooocoooooopboooooocooooooooooeootoooocoooooooobooooner) 


function growthewindowCtheWindow : 
Point; sizerect : 


WindowPtr; startpoint : 
Rect; var newportrect : Rect) : logical; 


procedure sizethewindowCtheWindow : 
Rect); 


WindowPtr; newrect : 


function trackthebox(theWindow : WindowPtr) : logical; 


CACO OOOO KK X ) 


inplementation 
Qoooocorooooococolocolorocooooorooooooooooeoooooooobocoooocooooooee) 


($R-) 
($5С+) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖКЖЖЖЖЖЖЖКЖЖЖКЖЖКЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
callWDEF 
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The inline code here is: WDEF :- WindowPeek( thew indow)* .windowdefproc; 


HLockCWDEF ); 
movea. | СР )+, Ad 
jsr AQ newrect := thewindow^.portRect; 
with thewindow^.portBits.bounds do 
That is, it pops the “address” argument into register Ай, OffsetRect(newrect, - left, - top); 
and then calls the routine at that address. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ') with newrect do begin 
function callWDEFCvariation : integer; thewindow : Win- 
dowPtr; message : integer; param : Ptr; address : Ptr) : long; if startpoint.v <= ((top + bottom) div 2) then begin 
inline $205F, %4Е90; pivot.v := bottom; 
offset.v := top - startpoint.v; 
(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ limitrect.top ‘= bottom - sizerect bottom; 
growthewindow limitrect.bottom := bottom - sizerect. (ор; 
end else begin 
This routine is an analog of the Toolbox trap GrowWindow; it pivot.v := top; 
follows mouse with a gray outline of the window’s new size. offset.v := bottom - startpoint.v; 
limitrect.top := top + sizerect.top; 
I’m going to draw in Window Manager port, and I’m going to limitrect bottom := top + sizerect.bottom; 
set the clipping to full screen (the low-memory global end; 
“grayrgn” contains a handle to the region consisting of 
everything but the menu bar). Since I don’t want to upset if startpoint.h <= (Cleft + right) div 2) then begin 
the Window Manager, 1711 save the old clip region first, so pivot.h := right; 
I can restore it at the end. The pen mode makes drawing its offset.h := left - startpoint.h; 
own inverse. This routine draws by calling the WDEF with a limitrect.left := right - sizerect.right; 
“wGrow” message. All this is in the Window Manager section limitrect.right := right - sizerect. left; 
of Inside Mac; I’m just approaching it from the other side. end else begin 
pivot.h := left; 
The mouse is down in one corner of the window. The offset.h := right - startpoint.h; 
diagonally opposite window is fixed for this operation; I limitrect.left := left + sizerect. left; 
call it the “pivot”. The mouse is probably not on the limitrect.right := left + sizerect.right; 
corner exactly; I use “offset” to correct the mouse end; 
position. And this corrected position will be corrected 
further to bring it within "limitrect^ if it strays outside. end; 
From here on, it’s simple. Draw the first outline; then, so if BitTst(Ptr(rom85), 0) then 
long as the mouse stays down, repeatedly erase it (by re- menuheight := 38 
drawing) and draw the new outline. When the mouse is else begin 
released, erase the outline and return the new portRect. theshort := shortpointer(mbarheight); 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖУ menuhe ight ‘= theshor t* + 18; 
function growthewindow(thewindow : WindowPtr; startpoint : end; 
Point; sizerect : Rect; var newportrect : Rect) : logical; if limitrect.top < menuheight then 
var limitrect.top := menuheight; 
savedport : GrafPtr; 
drawport : GrafPtr; newpoint := startpoint; 
savedclip : RgnHandle; AddPtCoffset, newpoint); 
thepointer : longpointer; 
WDEF : Handle; newpoint := PointCPinRectClimitrect, newpoint22; 
newrect : Rect; Pt2Rect(pivot, newpoint, newrect); 
west : logical; 
north : logical; dummy := callWDEFC2, thewindow, wGrow, @newrect, WDEF*); 
pivot : Point; Oldrect := newrect; 
offset : Point; 
limitrect : Rect; while StillDown do begin 
menuheight : integer; 
theshort : shortpointer; GetMouse(newpoint); 
dummy : long; AddPtCoffset, newpoint); 
oldrect : Rect; 
newpoint : Point; newpoint := PointCPinRectClimitrect, newpoint)); 
begin Pt2Rect(pivot, newpoint, newrect); 
GetPort(savedport); if not EqualRect(newrect, oldrect) then begin 
GetWMgrPor tCdrawport); dummy := callWDEF(0, thewindow, wGrow, @oldrect, 
SetPortCdrawport); WDEF*); 
dummy := callWDEF(0, thewindow, wGrow, @newrect, 
savedclip := NewRgn; WDEF ^); 
GetClipCsavedclip); oldrect := newrect; 
end; 
thepointer := longpointer(grayrgn); 
SetClipCRgnHandleCthepointer^ 22; end; 
PenMode(notPatXor 2; dummy := СӘТІНСЕР( , thewindow, wGrow, @oldrect, WDEF*); 


PenPat(gray); 
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HUn lock CWDEF ); 


PenNormal; 
SetClipCsavedcl ip); 
DisposeRgn(savedclip); 
SetPortCthewindow); 


oldrect := thewindow^ .portRect; 
LocalToGlobalColdrect.topleft); 
LocalToGlobalColdrect .botright); 


if EqualRectColdrect, newrect) then 
growthewindow :- false 

else begin 
newportrect := newrect; 
growthewindow := true; 

end; 


SetPort(savedport); 
end; 


CQXoloroloorooroorooroeoroorooroorooroooroorooooloooorooroooooocooooooocoooooooeex 
sizethewindow 


This routine is an analog of the Toolbox trap SizeWindow. 
It just precedes SizeWindow with MovePortTo, which moves the 
window without updating the screen. After this, I update 
the Window Manager port's clipping, so it will draw the 
window correctly. 
ЖЖЖАХЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖ) 
procedure sizethewindow(thewindow : WindowPtr; newrect : 
Rect); 
var 
drawpor t 
begin 


: GrafPtr; 


EraseRectCthewindow^ .portRect); 


with newrect do begin 
MovePortToCleft, top); 
SizeWindowCthewindow, right - left, bottom - top, 
false); 
end, 


InvalRectCthewindow^ .portRect); 


GetWMgrPor tCdrawport); 
SetPortCdrawport); 
SsetClipCwindowPeek( thew indow)* .strucrgn); 


setPor t( thew indow ); 
ClipAbove(WindowPeek( thew indow)); 
end; 


CQXokoloroorooorooorooooooroororoooooorooorooooooooooooooocooooooooooopdooek 
trackthebox 


This routine is a duplicate of TrackBox; I would use 
TrackBox but it isn't available in the old ROM. 


The idea is to highlight the zoom box, and then track the 
mouse while the button remains down. The zoom box should be 
highlighted when the mouse is in it, and unhighlighted when 
it is not. When the button is finally released, the routine 
returns true if the mouse is in the zoom box, and false if 


it is not. 
KK KK KKK KKK KK KKK KK KKK KKK KEK KKK KKK AER KK KKK KKK KKK KKK KKK KKK KEKE ) 


function trackthebox(thewindow : WindowPtr) : logical; 
var 
highlight logical; 
savedport : GrafPtr; 
drawport : GrafPtr; 
thepointer longpointer; 
WDEF : Handle; 
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thepoint 
thepart 
begin 
GetPort(savedport); 
GetWMgrPortCdrawport); 
SetPortCdrawport); 


: Point; 
: long; 


WDEF :- WindowPeek( thew indow)* .windowdefproc; 
HLockCWDEF ); 


thepart := callWDEFCO, thewindow, 
wDraw, Ptr(wInZoomIn2, WDEF*); 
highlight := true; 
while StillDown do begin 
GetMouse(thepoint); 
thepart := callWDEF(0, thewindow, 
wHit, Ptr(thepoint), WDEF^); 


if not highlight and (thepart = wInZoomIn) then 


begin 
thepart := callWDEF(0, thewindow, 
wDraw, PtrCwInZoomIn), WDEF ); 
highlight := true; 
end else if highlight and (thepart © wInZoomIn) 
then begin 
thepart := callWDEF(0, thewindow, 
wDraw, PtrCwInZoomIn), WDEF*); 
highlight := false; 
end; 
end; 


if highlight then 
thepart := callWDEF(®, thewindow, 
wDraw, Ptr(wInZoomIn), WOEF^); 


HUn lock CWDEF 5; 
SetPortCsavedport); 


trackthebox 
end; 
(655522222222225222225422524225225252252225252212222224223224425339 


end. 
(ЖЖЖХЖЖЖАЖЖЖАЖЖАЖЖААХЖАЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖАЖЖАЖАЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖ 


:= highlight; 


Listing: WDEF.p 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
WDEF .p 

WDEF for four-cornered window. 

(c) 1988, by Clifford Story & Attic Software 


KERR EKA KKK K KARA KKK KKK KEK EK KAKA KK KKK KKK EK KKK AKA KE KEKE ) 
unit WDEF; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У 


interface 
(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ') 


uses memtupes, quickdraw, osintf, toolintf, Common; 
(6225254525245525452254525452225254522222422222222224525252229) 
function windowdef (variation : integer; thewindow : Win- 
dowPeek; message : integer; param : long) : long; 
(ERK RK KKK KKK KKK KKK EK KKK EKA EKA KKK KKK KEK KKK KKK KEE KKK AKER KEKK) 


implementation 
( ЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


($R-) 
($Sc+) 


(KKK KKK KK KKK KKK AK KKK KKK KKK AAAA KEE AK KEKE KEKE 
datahandle 


This is horribly inefficient; each window saves the data for 
each BitMap in its datehandle. So each window duplicates 
this information (which must also be in the code, or where 
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would it come from?). I’ve got an assembler version of this 
WDEF that eliminates all this duplicate data; you could do 
it in Pascal by moving the StuffHex’s out of the init 


routine and into the draw routine. 
ЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖУ) 


type 
rectrecord = record 
dragrect : Rect; 
closerect : Rect; 
zoomrect : Rect; 
NWmap : BitMap; 
NWdata : array [1..28] of integer; 
NEmap : BitMap; 
NEdata : array [1..28] of integer; 
SWmap : BitMap; 
SWdata : array [1..8] of integer; 
SEmap : BitMap; 
SEdata : array [1..8] of integer; 
erasedata : erray [1..8] of integer; 
closemap : BitMap; 
closedata : array [1..9] of integer; 
zoommap : BitMap; 
zoomdata : array [1..9] of integer; 
end; 
rectpointer = ^rectrecord; 
recthandle = ^rectpointer; 
QDrecord = record 
randseed : long; 
screenbits : bitmap; 
arrow * cursor; 
dkgray : pattern; 
ltgray : pattern; 
gray : pattern; 
black : pattern; 
white ; pattern; 
theport : grafptr; 
end; 
QDpointer = “QDrecord; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖ) 


ргоседиге wdodraw(thewindow : WindowPeek; param : long); 
forward; 
function wdohit(thewindow : 
long; forward; 
procedure wdocalc(thewindow : 
procedure wdonew(thewindow : WindowPeek); forward; 
procedure wdodispose(thewindow : WindowPeek); forward; 
procedure wdogrow(therect : rectpointer); forward; 
procedure wdoicon(thewindow : WindowPtr); forward; 
(RK KKK KKK KR KKK KKK KK KKK KK KKK KKK KK KK KK KK KKK KKK KKK) 
function windowdef (variation : integer; thewindow : Win- 
dowPeek; message : integer; param : long) : long; 
begin 


WindowPeek; thepoint : Point) : 


WindowPeek); forward; 


windowdef :- 0; 


case message of 


“Оган : wdodraw(thewindow, param); 
wHit : windowdef := wdohitCthewindow, 
Point(param)); 
wCalcRgns : wdocalcCthewindow); 
wNew : wdonew( thew indow); 
wD іѕроѕе : wdodispose( thewindow); 
wGrow : wdogrow(rectpointer (param) ); 
wDrawGIcon : wdoicon(WindowPtr( thew indow)); 
end; 
end; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


QDglobals 


A WDEF can’t use globals, hence cannot reference the 
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Quickdraw globals directlu. This routine returns a pointer 
to the Quickdraw globals, which the WDEF can use instead. 
X Xookolooroooooooooooooooooooooooooroooroooooooooooooooooooooooodoe) 


function QDglobals : QDpointer; 


var 
thepointer longpointer; 
begin 
thepointer := longpointer(currenta5); 


thepointer := longpointer(Cthepointer^); 
QDglobals := QDpointerClongCthepointer^) 
- sizeof(QDrecord) + sizeof(grafptr)); 


end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
wdodraw 


This routine draws the window. There are two special cases: 
if the low word of the “param” argument is wInGoAway, then 
this is a call for close box highlighting; if it is 
wInZoomIn, then this is a call for zoom box highlighting. 


I draw the various parts of the window in order. First, I 
recalculate the various regions. Then I draw the window’s 
outline and shadow. Next is the title bar: outline the 
title bar, then erase its interior. Draw the title 
(truncated, if necessary, by clipping), then corners with 
CopyBits, and finally the horizontal lines between corners 
and the title. Last, draw the lower corners. Note that the 
corner brackets are drawn only if the window is highlighted. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ)) 


procedure wdodraw(thewindow : WindowPeek; param : long); 


var 
therect : Rect; 
width integer; 
limitrect : Rect; 
savedclip : RgnHandle; 
height integer; 
index integer; 

begin 


with thewindow^, QDglobals*.thePort* do begin 
if visible then begin 


HLockCdataHandle); 
with recthandle(dataHandle)** do begin 


if LoWord(param) = wInGoAway then begin 
closemap.baseAddr := @closedata; 
CopyBits(closemap, portBits, closemap.bounds, 
closemap.bounds, srcXor, nil); 
end else if LoWord(param) = wInZoomIn then 
begin 
zoommap .baseAddr := @zoomdata; 
CopyBitsCzoommap, portBits, zoommap.bounds, 
zoommap.bounds, srcXor, nil); 
end else if param = 0 then begin 


wdocalc( thewindow); 


FrameRgn(strucrgn); 

therect := strucrgn^^.rgnBBox; 

with therect do begin 
MoveToCleft, bottom - 2); 
LineToCright - 2, bottom - 2); 
LineTo(right - 2, top); 

end; 


therect := dragrect; 
InsetRect(therect, 1, 1); 
EraseRect(therect); 
FrameRect(dragrect); 
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wlth dragrect do 


width := (right + left - titlewidth)dlv 2; 


just testing for specific rectangles. 
XXXXKXKXKXKXXKXXKXXKXXKXXKXKXXXXXKXXIXXXXXXXXXXXXXXXXXXXXXXXXKXXX) 


function wdohit(thewindow : WindowPeek; thepoint : Point) : 


1f width < NWmap.bounds.right then long; 
width := NWmap.bounds.right + 3; label 
100, 200; 
limitrect.left := NWmap.bounds.right; var 
limitrect.top := NWmap.bounds.top - 2; therect : Rect; 
limitrect.right := NEmap.bounds.left - 3; begin 
limitrect.bottom :- NWmap.bounds.bottom * 2; 
wdocalcCthewindow); 
savedclip := NewRgn; 
GetClipCsavedclip); with thewindow^ do begin 
ClipRectClimitrect); 
SectRgn(savedclip, clipRgn, clipRgn); HLockCdataHandle); 
with recthandle(dataHandle)** do begin 
MoveTo(width, dragrect.bottom - 5); 
DrawStringCtitlehandle^^); wdohit := wNoHit; 
SetClipCsavedcl ір); 1f hilited then begin 
DisposeRgn(savedclip); therect := strucrgn^^.rgnBBox; 
if (thepoint.v > Ctherect.top + 8)) 
if hilited then begin T and (thepoint.v < Ctherect.bottom - 82) 
en 
NWmap.baseAddr := eNWdata; goto 100; 
CopyBits(NWmap, portBits, NWmap.bounds, if (thepoint.h > Ctherect. left + 8)) 
NWmap.bounds, srcCopy, nil); and (thepoint.h < Ctherect.right - 8)) 
then 
NEmap.baseAddr := @NEdata; goto 100; 
CopyBits(NEmap, portBits, NEmap.bounds, wdohit := wInGrow; 
NEmap.bounds, srcCopy, nil); goto 200; 
end; 


if (width - 7) > NWmap.bounds.right then 


begin 100: if PtInRectCthepoint, closerect) and hilited and 
height := closerect.top; goAwayF lag then 
for index := 1 to 6 do begin wdohit := wInGoAway 
MoveToCNWmap.bounds.right, height); else if PtInRectCthepoint, zoomrect) and hilited 
LineTo(width - 7, height); then 
MoveCtitlewidth * 13, 0); wdohit := wInZoomIn 
LineToCNEmap.bounds.left - 1, height); else if PtInRect(thepoint, contrgn^^.rgnBBox) 
height := height + 2; then 
end; wdohit := wInContent 
end; else if PtInRect(thepoint, dragrect) then 
wdohit := wInDrag; 
end; 
end; 
1f hilited then begin HUnlockCdataHandle); 
SEmap.baseAddr := @SEdata; 
SWmap.baseAddr := @SWdata; end; 
end else begin 
SWmap.baseAddr := @erasedata; 200: end; 
SEmap.baseAddr := @erasedata; 
end; ( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
wdocalc 
CopuBits(SWmap, portBits, SWmap.bounds, === 
SWmap.bounds, srcCopy, nil); This routine calculates all regions and rectangles in the 
CopyBits(SEmap, portBits, SEmap.bounds, window. Note these are all in local coordinates, and that 
SEmap.bounds, srcCopy, nil); I assume that window’s portBits.bounds.topleft is the point 
(0, 0). 
end; ЖКК КККК) 
епа; procedure wdocalc(thewindow : WindowPeek); 
HUnlock(dataHandle); ver 
end; therect : Rect; 
end; begin 
end; 


with thewindow^ do begin 
(KKK KKK KKK KKK KK KK KKK KKK KK KK KK KKK KK KK KKK KKK KKK KKK KK KKK KK KK 
wdohit therect := port.portRect; 
PUR with port.portBits.bounds do 
This routine hit-tests a point, and returns window part that OffsetRectCtherect, - left, - top); 
the point lies in. The first section tests for the grow 
brackets; if the point is near the top, and also near the OpenRgn; 
left edge, then it’s in top-left bracket, ect. Note that MoveToCtherect.left + 1, therect.top); 
unhighlighted windows don't have grow brackets. The rest is LineToCtherect.right - 1, therect.top); 


304 @ The Best of MacTutor, Vol. 5 


LineToCtherect.right - 1, therect.bottom - 9); 
LineTo(therect.right - 9, therect.bottom - 9); 
LineTo(therect.right - 9, therect.bottom - 1); 
LineTo(therect.left + 9, therect.bottom - 1); 
LineTo(therect.left + 9, therect.bottom - 9); 
LineTo(therect.left + 1, therect.bottom - 9); 
LineToCtherect. left + 1, therect.top); 
CloseRgn(contrgn); 


with recthandleCdateHandle)^^, therect do begin 
SetRect(dragrect, left, top - 19, right, top); 
SetRect(closerect, left + 12, top - 15, left + 23, 
top - 4); 
SetRect(zoomrect, right - 23, top - 15, right - 12, 
top - 4); 
SetRect(NWmap.bounds, left + 1, top - 18, left + 
33, top - 4); 
SetRect(NEmap.bounds, right - 33, top - 18, right - 
1, top - 45; 
SetRect(SWmap.bounds, left * 1, bottom - 9, left * 
9, bottom - 1); 
SetRectCSEmap.bounds, right - 9, bottom - 9, right 
- 1, bottom - 1); 
SetRect(closemap.bounds, left + 13, top - 14, left 
+ 22, top - 5); 
SetRect(zoommap.bounds, right - 22, top - 14, right 
= 1$. top =D); 
end; 


therect.top 

OpenRgn; 
MoveToCtherect.left, therect.top); 
LineToCtherect.right, therect.top); 
LineToCtherect.right, therect.top * 12; 
LineToCtherect.right + 1, therect.top + 1); 
LineToCtherect.right * 1, therect.bottom * 12; 
LineToCtherect.left + 1, therect.bottom + 1); 
LineToCtherect.left * 1, therect.bottom); 
LineToCtherect.left, therect.bottom); 
LineToCtherect.left, therect. top); 

CloseRgn(strucrgn); 


:= therect.top - 19; 


end; 


end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
wdonew 
This routine is called bu GetNewWindow, so WDEF can set up 
its private data, which is just what I do here. A11 those 
BitMaps were carefully calculated with screen shots and fat 
bits, and at a Severe cost to my eyesight! 
XKXXXXXXXKXXXXXKXXXKXXXXXXXXXXXKXXXXKXXXXXXXXXXXXXXXKXXXXKXKXKXKXKXK) 
procedure wdonew(thewindow : WindowPeek); 
begin 


with thewindow^ do begin 


dataHandle := NewHandle(sizeof(rectrecord)); 
HLockCdataHandle?); 
with recthandleCdateHandle)^^ do begin 


with NWmap do begin 
baseAddr := @NWdata; 
if goAwayFlag then 
| Stuf fHexCbaseAddr, 
“010000000 10000000 1000000 1F5FFDFF 10 100400 17 
DOQ5FF 10 100400F 10005ҒҒ00 100400 7FDOOSFF 00 100400 TF DOQoFF 0 100400 TF DFFOFF ’ 2 
else 
StuffHexCbaseAddr, "010000000 10000000 100000 
OIF TFFFFF 10000000 17FFFFFF 10000000Ғ ТЕҒҒҒҒҒ00000000ТҒҒҒҒҒҒҒ0О00000007Ғ 
FFFFFF00000000TFFFFFFF ^); 
rowBytes := 4; 
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end; 


with NEmap do begin 

baseAddr := @NEdata; 

StuffHexCbaseAddr, ”000000800000008000000080ҒЕВҒҒ 
АҒ800208808ҒҒА08ВЕ800208808ҒҒА08ВЕҒ00208800ҒҒВҒВВҒЕО0200800ҒҒА 
008ҒЕ00200800ҒҒВҒЕВҒЕ”); 

rowButes :- 4; 

end; 


with SWmap do begin 
baseAddr := @SWdata; 
StuffHex(baseAddr, 
*F000 1000 1000 1000 1F 000 1000 1000 100”); 
rowButes :- 2; 
end; 


with SEmap do begin 
baseAddr := @SEdata; 
Stuf fHex(baseAddr , 
'@F00080008000800F800800080008000  ); 
rowButes := 2; 
end; 


StuffHex(@erasedata, 
“00000000000000000000000000000000”); 


with closemap do begin 
baseAddr := @closedata; 
Stuf fHexCbaseAddr, 
'080049902A000000€E38000002^40049000800 ' ); 
rowBytes := 2; 
end; 


with zoommap do begin 
baseAddr := @zoomdata; 
Stuf fHexCbaseAddr, 
*0C004D002E000400E780FC002A0049000800:); 
rowBytes := 2; 
end; 


end; 
HUnlock(dataHandle); 


end; 
wdocalc(thewindow); 
end; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
wdodispose 


This routine is called bu DisposeWindow so the WDEF can 
clean up its private data. 


MEKKEKKK KKK AK AK ERK AK ERK EKER KKK KKK KEK KKK AKA KKK KA KKK KKK KK KKK ) 


procedure wdodispose(thewindow : WindowPeek); 
begin 


DisposHandle( thewindow* .dataHandle); 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
wdogrow 

This routine draws a gray facsimile of the window, using the 

rectangle it is passed as the portRect. It is called by 

GrowWindow Cin this program, by "growthewindow^). 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖАЖЖЖЖЖЖЖ, 

ргоседиге wdogrow(therect : rectpointer); 

begin 
with therect^ do begin 
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Movelo(dragrect.left, dragrect.top - 18); 
LineTo(dragrect.right, dragrect.top - 18); 
LineToCdragrect.right, dragrect.bottom); 
LineTo(dragrect.left, dragrect.bottom); 
LineToCdragrect.left, dragrect.top - 18); 


Movelo(dragrect.left, dragrect.top); 
LineTo(dragrect.right, dragrect.top); 


end; 


end; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХАЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


wdoicon 
This routine is supposed to draw the grow icon. This window 
doesn't have a grow icon, so it onlu draws the outline for 
scroll bars. 
ЖЖЖЖЖАЖЖЖЖЖЖЖХАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 
procedure wdoicon(thewindow : WindowPtr); 
var 
savedport 
begin 
GetPortCsavedport); 
SetPor tC thew indow); 


: GrafPtr; 


with thewindow^.portRect do begin 
MoveToCleft, bottom - 15); 
LineToCright, bottom - 15); 
MoveloCright - 15, top); 
LineToCright - 15, bottom); 

end; 


SetPort(savedport); 


end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖ) 


end. 
(BKK RK KKK KKK KK EK KKK KKK KKK KK KKK KKK KKK EK KEKE KKK KKK KKK KKKKE ) 


Listing: 


/^%ЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖ 


Corners.r 

Resources for four-cornered window. 

(c) 1988, by Clifford Story & Attic Software 
JOCODODODOOODOOOOOODODOODODODOOOODODOOOODOOOOODODOOOOOOOOOOOOr / 


8include *types.r"^ 
/^%ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖ 


Menu resources 
KAKKKAKK KAKA KEK AKASAKA AKA AAA ARK EKEK EEE ER EKER KAKA KAKA k / 
resource ‘MENU’ (1001, preload) ( 
1081, 
textMenuProc, 
QxTFFFFFFB, 
enabled, 
epple, 
( /* array: 3 elements */ 
/* (1) */ 
"About Corners...", 1, “^^, *^ plain, 
/* [2] */ 
"About Attic Software...^, noicon, “?”, “? plain, 
/* [3] */ 
“-% nolcon, "^, "^, plain 


Corners.R 


); 


resource ‘MENU’ (1002, preload) ( 
1002, 
textMenuProc, 
üxTFFFFFFO9, 
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enabled, 
“File”, 
( /* array: 4 elements */ 
/* (1) */ 
“New”, noIcon, "N^, ““ plain, 
/* (2) */ 
“Close”, noIcon, "K^, *# plain, 
/* [3] */ 
*-^, nolcon, "^, *“ plain, 
/* [4] */ 
) “Quit”, noIcon, *Q^, ^^, plain 
); 


resource ‘MENU’ (1003, preload) ( 

1003, 

textMenuProc, 

@xTFFFFFFD, 

enabled, 

“Edit”, 

( /* array: 6 elements */ 
/* (1) */ 
“Undo”, noIcon, "Z^, *", plain, 
/* [2] */ 
“-% nolcon, "^, "^, plain, 
/* [3] */ 
“Cut”, noIcon, "X^, “”, plain, 
/* [4] */ 
“Сору”, noIcon, "C^, "^, plain, 
/* [5) */ 
“Paste”, noIcon, "V^, "^, plain, 
/* (6) */ 

“Clear”, noIcon, *", "", plain, 

); 


/^*Ж^ЖЖЖЖЖЖЖХХХЖХЖХЖХЖЖЖАЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Picture resources 

HKRA KK AK AKA RK ERK AR KEKE SAREE K AER ARE EAE A AEA ХХХ ХХ AA AK KEKE KEKE / 

resource ‘PICT’ (1001, “About”, purgeable) ( 
1081, 
(7, 1, 308, 499), 
%”1101 А000 82А0 008С 0100 0А00 0700 0701" 
%”3401 F30A 0000 0000 0000 0000 0800 1800" 
%”1844 0009 0009 0132 O1F1 0700 0200 0248" 
%”А100 9600 0606 0000 0002 03A1 009A 0008" 
$"FFFD 0000 0004 0000 А000 9803 0003 0000" 
$"0428 012A 0026 22A9 2031 3938 3820 6279" 
$"2043 6C69 6666 6Ғ72 6420 5374 6Ғ72 7920" 
$2616E 6420 4174 7469 6329 АС22 2053 6F66" 
$77477 6172 652C 2050 2E4F 2E20 426Е 7820" 
%”3231 392C 2047 6F6C 6574 612C 2043 29А6" 
%”1161 6C69 666Ғ 726Е 6961 2020 2039 3331" 
$3136 A000 99A0 0097 А100 9600 0606 0000" 
%”0002 03A1 009A 0008 FFFA 0000 0027 0000" 
%”А000 9804 0500 0012 2800 2000 Е007 436Ғ” 
%”726Е 6572 73A0 0099 А000 97A1 0096 0006" 
$"0500 0000 0203 A100 9А00 0800 4400 0000" 
$"DAOD 00А0 0098 0400 0000 0С28 0057 001Е” 
%%2254 6869 7320 7072 6Ғ67 7261 6020 6465" 
$^6D6F 6E73 7472 6174 6573 2061 6E20 696E” 
%%7465 7229 E022 6573 7469 6Е67 2065 7874" 
$^656E 7469 6F6E 206Ғ 6620 7468 6520 4061" 
$^6369 6E74 6F73 6800 А000 99A1 009A 0008" 
%%0034 0000 000А 0000 А200 9828 0067 001Е” 
$"2269 6Е74 6572 6661 6365 3А20 2077 696E” 
%”646Е 7773 2074 6861 7420 6361 6Е20 6265" 
$^2072 6529 0622 2073 697A 6564 2066 726F" 
$^6020 616E 7920 636F 726E 6572 2028 696Е” 
$27374 6561 6420 6F66 2907 0100 А000 99A1" 
%”009А 0008 0024 0000 000А 0000 А000 9828" 
$"0071 001Е 226F 6E6C 7920 6672 6F6D 2074" 
%”6865 206С 6F77 6572 2072 6967 6874 292Е” 
$22020 4561 6368 2029 СҒ22 636Ғ 726Е 6572" 
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); 


%%2068 
%%6368 
%%”009А 
%%0087 
%%6720 
%%7573 
$^6F6E 
$"00DA 
$^99A1 
$^9824 
$*2074 
$”756C 
$6265 
$^бЕ2@ 
$^@@0А 
%%7068 
$6573 
$“D420 
$"2020 
$7200 
$"0000 
$^616D 
$^6174 
%”6А75 
$7220 
$7469 
%”08ҒҒ 
%”1Е22 
$7920 
$4061 
$6963 
$2066 
%%0000 
%”6173 
%”652Е 


resource 


1125, 
(ТТ, 
$^1101 
$3201 
$^ 1844 
%”А 100 
$"FFFA 
%%0000 
$1471 
$0500 
$"E600 
%%2241 
%%6973 
$*746Е 
$ *696Е 
$6275 
$^209A 
$^0050 
$2020 
$7920 
$6465 
$^1265 
$”6572 
%”00Е6 
$“6F75 
%%726Ғ 
0818 
%”7072 
%”А100 
%%2800 
%%1С00 
$^6361 
$^1920 
$^9A00 
$0 100 
$2000 


6173 
6574 
0008 
09 1E 
6A75 
1561 
2Е00 
0000 
009A 
1022 
6869 
6420 
206D 
6 12D 
0000 
6963 
1320 
2014 
5468 
А000 
А000 
2069 
2061 
1374 
1468 
2900 
C400 
696E 
3 139 
6320 
6820 
156C 
000А 
6361 
А000 


206 1 
0320 
00 14 
2279 
1374 
6C20 
A000 
A000 
0008 
9169 
1320 
1072 
6F73 
A000 
A000 
1320 
1573 
6578 
6973 
99A1 
9828 
1320 
6C6C 
2061 
6520 
0463 
0000 
2074 
3839 
29D7 
696E 
6С00 
0000 
6C20 
99А0 


2002 
7768 
0000 
6F75 
206С 
6729 
99A1 
9828 
FFF4 
6Е64 
6665 
29E 1 
7420 
99A 1 
9828 
7072 
6566 
7420 
2070 
009А 
00С7 
6F66 
3B20 
2074 
436F 
6C65 
DABO 
6865 
2069 
1F54 
636C 
A000 
A000 
736F 
0097 


6772 
6963 
000А 
2063 
6968 
CFOA 
009A 
0097 
0000 
6F77 
6174 
1B6F 
1573 
009А 
0087 
6F67 
156C 
1012 
6172 
0008 
001Е 
206Е 
6974 
6561 
126Е 
00А0 
00А0 
2046 
1373 
1574 
1564 
99A 1 
9828 
1572 
A000 


6F77 
680D 
0000 
616Е 
6520 
726Ғ 
0008 
001Е 
000А 
7320 
1572 
6261 
6566 
0008 
001Е 
7261 
2069 
6F67 
7469 
FFD4 
2270 
6F20 
2773 
1365 
6572 
0099 
0098 
6562 
7565 
6F72 
6573 
009A 
00Е7 
6365 
8DAQ 


2062 
А000 
A200 
2064 
1468 
1120 
0004 
010D 
0000 
1169 
6520 
626C 
T56C 
FFE4 
2267 
6D2C 
6Е20 
1261 
6375 
0000 
726Е 
1573 
2029 
1220 
1320 
A100 
2800 
1275 
206F 
2020 
2074 
0008 
00 1E 
2063 
0083 


7261" 
99A 1" 
9828" 
7261" 
6520" 
6963" 
0000" 
А000" 
A000" 
7468" 
TI6F^ 
7920" 
2069" 
0000" 
7261" 
206C” 
6129" 
602Е” 
6C61" 
00DA^ 
6772" 
6520" 
C622" 
666F ” 
6172" 
9AQQ" 
0700" 
6172" 
6620" 
7768" 
6865" 
FFB4" 
1350" 
6F64" 
FF” 


‘PICT’ (1002, "Attic", purgeable) ( 


306, 
A000 
F 10A 
0009 
9600 
0000 
122B 
6172 
0000 
00А0 
1474 
2061 
1329 
6720 
1369 
0008 
0010 
5765 
6F66 
616C 
7761 
2C0D 
0000 
1220 
6475 
6F 20 
6F67 
9A00 
1000 
0000 
6Е20 
6061 
0800 
A000 
A000 


497), 


82А0 008С 0100 0А00 


0000 
0009 
0606 
0048 
ВА2В 
65А0 
0203 
0098 
6963 
2073 
DC22 
636F 
6E65 
004C 
2213 
2064 
2077 
696E 
1265 
A000 
A000 
6265 
6374 
646F 
1261 
0800 
100 1 
E600 
6265 
696C 


0000 
0130 
0000 
0000 
0Е41 
0099 
А 100 
0400 
2053 
6D61 
6820 
6D70 
1313 
0000 
696Е 
6F20 
6F29 
6572 
206F 
99A1 
9828 
1314 
2E20 
2063 
6D6D 
2000 
00А0 
00А0 
2012 
2061 


0000 
Ø 1EF 
0002 
А000 
7474 
А000 
9А00 
0000 
6F66 
6C6C 
7072 
616E 
29E2 
00Е6 
6365 
6120 
0722 
D32C 
1514 
009A 
0060 
206В 
2057 
6F6E 
696E 
0000 
0099 
0098 
6561 
743A 


0000 
0700 
03А1 
9803 
6963 
97А1 
0800 
0С28 
1411 
204D 
6F67 
192Е 
0100 
0000 
2031 
1661 
1268 
2061 
6C69 
0008 
0010 
6E6F 
6520 
1412 
672E 
E600 
A100 
2A 10 
6368 
00А0 


0С00 0000 Е600 00А0 
99A1 009A 0008 FFFC 
982A 1022 2020 2020 


0700 
0800 
0200 
009A 
0003 
2053 
0096 
5000 
0040 
6172 
6163 
1261 
2069 
А000 
A000 
3938 
1269 
3820 
2073 
2901 
003С 
2269 
116Е 
616C 
6163 
00А0 
00А0 
9А00 
157 
6564 
0099 
0098 
0000 
2020 
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0101" 
1800" 
0248" 
0008" 
0405" 
6F66" 
0006" 
0000" 
00 10^ 
6520" 
696E” 
6D6D" 
6E20" 
99A1" 
9828" 
362E" 
6574" 
D249" 
6861" 
056E” 
0000" 
1320" 
2070" 
1329" 
1420" 
0099" 
0098" 
0800" 
6520" 
2062" 
A100" 
2A 10" 
00Е6" 
2020" 


%%2020 2020 2020 2020 2020 2020 2020 2020" 
%%2020 2020 2020 2041 7474 2991 0С69 6320" 
$^536F 6674 7761 7265 00Ай 0099 А100 9400" 
$"08FF ЕС00 0000 E600 00А0 0098 2800 8000" 
%”1022 2020 2020 2020 2020 2020 2020 2020" 
$"2020 2020 2020 2020 2020 2020 2020 2020" 
%72050 2E4F 298F 0А2Е 2042 6Ғ78 2032 3139" 
%”00А0 0099 A100 9А00 08ҒҒ DCOO 0000 E600" 
%”00А0 0098 2800 С000 1022 2020 2020 2020" 
%%2020 2020 2020 2020 2020 2020 2020 2020" 
%%2020 2020 2020 2020 2047 6Ғ6С 2090 1865" 
%%7461 2C20 4361 6С69 666F 726E 6961 2020" 
$"2039 3331 3136 0DAO 0099 А100 9А00 08ҒҒ” 
%“СС00 0000 E600 00А0 0098 2800 0000 1001" 
%”00А0 0099 A100 9400 08ҒҒ ВС00 0000 E600" 
$ OOAD 0098 2410 2257 6520 616C 736F 206Ғ” 
977065 7261 7465 2061 2062 756C 6C65 7469" 
%”6Е20 626Ғ 6172 6420 7329 0422 7973 7465" 
$^6D20 6174 2028 3830 3529 2036 3833 2030" 
%%3332 322C 2062 6574 7765 656E 2074 29E6" 
$^0368 6500 A000 99A1 009A 0008 FFAC 0000" 
$"00E6 0000 А200 9828 ØØFD 0010 2268 6Ғ75" 
$7273 206F 6620 363A 3030 2050 4020 616E” 
$^6420 323A 3030 2041 4D2C 2050 6163 6929" 
$^D822 6669 6320 7469 6065 2C20 7365 7665" 
$^6Е20 6461 7973 2061 2077 6565 682Е 2020" 
$^506C 6561 2903 0373 6500 A000 99A1 009A" 
$^0008 FFOC 0000 00Е6 0000 А000 9828 0100” 
$"001D 1566 6565 6С20 6672 6565 2074 6F20" 
$^6361 6C6C 2069 6E21 A009 99A0 0097 A100" 
$"9600 0606 0000 0002 03A1 009A 0008 ҒҒҒ0” 
$0000 0060 0000 А000 9800 000A 2873 1722" 
%”А920 3139 3838 2062 7920 436C 6966 666Ғ” 
$^1264 2053 746F 7279 2061 6E64 2041 7474" 
$^6963 29AC 0920 536F 6674 7761 7265 A000" 
%”99А0 0097 A000 80А0 0083 ҒҒ” 


/^*^*ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖ 


Window resource 
JOOODOODODODOCOCOOOOOOOOOEECOOOOOOOODOODOOOOOOOOOOOOOOOOOOEOOOK / 
resource ‘WIND’ (1001, purgeable, preload) ( 

(0, 0, 209, 320), 

800, 

invisible, 

goaway, 

0x0, 

“untitled” 
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/Ж*Х®ХЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Scroll bar resource 
OCOODOODOODOODOODOOOOOOOOOOOOEOOOROOOOEOROOOOOOOOIOOOOIOOOOOOOOOOOEEC / 
resource 'CNTL^ (1001, purgeable, preload) ( 

(0, 0, 16, 50), 

Ke п b 

invisible, 

1, 

1, 

scrollBarProc, 

0, 

NW Rn 


M 


/YYYXXKXXKXKXKXXKXXXKXXXXXXKXXXXXXXXXXXXXXXXXXXXXXXXKXXXXXXXXXXKXK 
Bundle resources 
XOoOOOOOOOOOOIOOOOOOOCOOOOOOOOOOOIOOOOOOOOOIOODOOOOIOODOOOIOEEEEEEXE / 
resource 'BNDL^ (1001, “Corners”) ( 
‘CORN’, 
0, 
( /* array ТуреАггау: 2 elements */ 
/* [1] */ 
' [CN ^, 
( /* array IDArray: 1 elements */ 
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уж L1] */ 
0, 1001, 


), 

/* [2] */ 

‘FREF’, 

( /* array IDArray: 1 elements */ 
/* (1) */ 
0, 1001, 


) 
); 


/ XXX eoccpeococooocegnoroooopeocboooopoobceooocpeoooooopooboebeeeeeeceexx 


File reference resource 
X xooooooeoooeooocoboooopboocecbooroboocoeocepeooeoooooooeoeoeceeeeeeex / 
resource ‘FREF’ (1001, "CORN APPL^, purgeable) ( 

‘APPL’, 

0, 

Wa 


); 


/EXYXXXXXXFXXKXXXXXKXKXXXX1XXXXX1XX1XXX1XKXKXXXX1XXXX1XXXXXXXKXXXXXXXKXKEK 
Icon list resource 
ЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖ / 
resource ‘ICN®’ (1001, “APPL Icon”, purgeable) ( 
( /* array: 2 elements */ 
/* (1) */ 
$^0000 0000 ТЕҒЕ FFFE 4040 0202 4040 0202" 
$"4040 0202 47C0 03Е2 4400 0022 4400 0022" 
$^4400 0022 7С00 003Е 4000 0002 4000 0002" 
$"4000 0002 4000 0002 4000 0002 4000 0002" 
$"4000 0002 4000 0002 4000 0002 4000 0002" 
$"4000 0002 4000 0002 7С00 003E 4400 0022" 
$"4400 0022 4400 0022 47С0 03Е2 4040 0202" 
$"4040 0202 4040 0202 TFFF FFFE", 
/* [2] */ 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
$"FFFF FFFF FFFF FFFF FFFF FFFF, FFFF FFFF^ 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF* 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF* 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒЕҒ” 
) 
m 


/ FX XoXocccoerororocereerorooooccooooocooobooooocooodobocooodoeooecoopooeceexex 


Icon resource 
XXXXXXXXXXXKXXXXXXXXXXXXXXXXX1XXXXXXXXX1XF1KXXKXXXXXKXKKXKXXKKXXK / 
resource ‘ICON’ (257, purgeable) ( 
%%0000 0000 ТЕРЕ FFFE 4040 0202 4040 0202" 
$"4040 0202 47С0 03Е2 4400 0022 4400 0022" 
$"4400 0022 7С00 003Е 4000 0002 4000 0002" 
$"4000 0002 4000 0002 4000 0002 4000 0002" 
%”4000 0002 4000 0002 4000 0002 4000 0002" 
$"4000 0002 4000 0002 1С00 003Е 4400 0022" 
%%4400 0022 4400 0022 47С0 03Е2 4040 0202" 
%”4040 0202 4040 0202 TFFF FFFE’, 


[ FX XXxoxoocecioocooooooocpboeoooooooooocoeoooocoboocooocooooocooooooceer 


Finder resource 
HR KKK KKK KKK RK KKK KKK KK KK HK KEK / 
data ‘CORN’ (0, purgeable) ( 

%”50А9 2031 3938 382C 2062 7920 436C 6966" 
/* P@ 1988, by Clif */ 

$"666F 7264 2053 746Ғ 7279 2026 2041 7414" 
/* ford Story & Att */ 

$”6963 2053 6F66 7477 6172 6500 502Е 4F2E" 
/* ic Software-P.0. */ 

%%2042 6F78 2032 3139 0047 6F6C 6574 612C" 
/* Box 2195Coleta, */ 

$"2043 616C 6966 6F72 6E69 6120 3933 3131" 
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/* California 9311 */ 

$736" ЭРИ 

; 
[ oeeeoooooooooeoooooooco ooo co oec ee eeeeboeooococebebbeooooobe ee ee ee 
Multif inder resource 
Xxooooocoooeobooooocceooooeceeoecoeopeoc pec epo AREA RA AAA EA ELEY / 
resource ‘SIZE’ (-1) { 

saveScreen, 

acceptSuspendResumeEvents, 

enableOptionSwitch, 

cannotBackground, 

MultiFinderAware, 

98304, 

98304 
); 


/^ХЖХЖЖХЖХЖЖХЖЖЖАЖЖЖЖХЖАЖЖАЖЖАЖЖЖЖЖЖЖАЖЖАЖЖАЖЖЖАЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖ / 


Listing: Corners.meke 


RKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKEKKKE 
8 Corners .make 


= (c) 1988, by Clifford Story & Attic Software 
RKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKEKKKKKKKEKKKKKKKKKKKKKKKKKKKKE 


НЖЖЧ*ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
# compile resources 
ПЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Corners ff Corners.make Corners.r 

Rez Corners.r -append -o Corners 


ЯЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖУЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖУЖЖЖЖЖЖЖЖ 
Я compile common declarations 
ПНЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Соттоп.р.о f Corners.make Common.p 

Pascal Common.p 


ИЖЖЖАХҖХҖААЖАЖХЖАХЖҖХЖЖАЖЖЖЖАЖХЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖАЖАЖЖЖЖЖАЖАЖЖЖХАХЖЖЖАЖЖХАЖЖЖЖЖЖЖЖЖЖ 


8% compile and link WDEF 
ЯЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖУЖЖЖЖУЖЖЖУЖЖУЖЖЖЖЖУЖЖЖЖЖУЖЖЖЖЖЖЖЖЖ 
WDEF.p.o f Corners.make WDEF.p Common.p.o 
Pascal WDEF .p 
Corners ff Corners.make WDEF.p.o 
Link -m WINDOWDEF -w -t ‘APPL’ -c ‘CORN’ ò 
-rt WDEF=50 -sn Main=’Four Corners’ à 
WDEF.p.o à 
* (Libraries)"Interface.o д 
*" (Libraries)"Runtime.o à 
* (PLibraries)^PasLib.o д 
* (PL ibraries)"SANEL ib.o ò 
-o Corners 


НЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
* compile ROM replacements 
RKKKKKKKKKKKKKKK KKK KKK KKK KKK KE KEKE KKK KKK KK KKK KKK KKK KKK AKKKKES 
Patches.p.o f Corners.make Patches.p Common.p.o 

Pascal Patches.p 


НЖЖЖЖЖЖЖЖХЖЖЖЖХЖХЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


® compile and link Corners 
ПҢЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖ 
Corners.p.o f Corners.make Corners.p Patches.p.o 
Pascal Corners.p 
Corners Corners.make Corners.p.o 
Link -w -t APPL -c ‘CORN’ д 
Corners.p.o à 
Patches.p.o à 
" (Libraries)"Interface.o д 
* (Libraries) "Runtime.o à 
* (PLibraries)^PasLib.o д 
" (PLibraries) "SANELib.o д 


-o Corners 
fGooooooooooooocooocooocoooobdoooooooooooooeoboboeoeobeoooooeeeeeer 


[e 


cito, 
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ABC's of Macintosh 
Designer CDEFs 


Designer CDEFs 

I was hunting around the office for software goodies a while 
back when I came across Prototyper™ . I stuck the disk in to see 
what it was and was pleasantly surprised. Those hours spent 
getting the interface just right seemed over. Here was an 
environment where I could draw my windows, set up my menus 
and controls, and then let it generate the code for the interface. 

Prototyper™ wasn’t everything I wanted it to be, though. 
For example, it would generate code for things I didn't need. But 
it served my purpose of getting an interface/shell running 
quickly. (I hear version 2.0 is a lot better, but they haven’t sent 
MacTutor an upgrade yet.) Anyway, I decided to test Proto- 
typer™ out on graphic research question—Yahtzee (relaxation 
is important to mental health). 

Well, after a bit, Ihad it up and running. I took it home and 
stuck it in my Mac for my recently married bride to look at. She 
took the mouse and started playing the game. Notas skilled in the 
mouse as I, whenever she went to click the checkbox beside each 
die to re-roll, she kept on missing or resetting it. 

She asked me why she couldn’t just click on the dice 
themselves instead of those little, tiny boxes. I was about to say 
that they weren’t controls when I thought, “Why not? The user 
is always right.” And so I went on thinking about the problem. 
CDEFs sounded like a lot of work, but they weren’t for what I 
wanted. I just wanted a variation of the checkboxes. I decided 
justto alter the drawing routine of my checkboxes so that they just 
put a rounded rectangle around the die picture when selected. I 
found that this was quite easy to do and wrote up a small 
demonstration. 


The Demo 

The demo puts up five altered buttons (figure 1). The one in 
the middle is an altered checkbox made to look like a light switch. 
Itis used to deactivate the controls on the left or right side. There 
are three radio buttons on the left which take on the appearance 
of a traffic light. The last button on the right is an altered button 
that cycles through the faces on a die (pictures taken from my 
Yahtzee application). 


The CDEF 


A CDEF is called through a function of the form: 
function myCDEFProc(varCode : integer; 
theControl : ControlHandle; 
message : integer; 
param : longint) : longint; 
It returns a longint telling what part of the control was 


pressed or zero if not pressed. The parameter var Code contains 
the variation code of the control. Itlets you write one CDEF for 
a variety of controls. I chose though to use the RefCon field of 
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Figure 1. Designer CDEF 


the control, theControl, to switch between routines. The message 
parameter tells the CDEF function what it needs to do. The last 
parameter, param, varies in meaning depending on message. 

The unit that held my designer CDEF is called *myCDEF". 
A CDEF is supposed to handle a lot of tasks. It must take care of 
drawing the control according to it's value and hilighting, as well 
as determining if the control was actually pressed. Therefore the 
main routine of our CDEF function is one where we check the 
message parameter that was passed, and do one of three routines: 
drawing, testing for a hit, and calculating the region. Other 
routines such as initializing or dragging the indicator are either 
done for us or not needed. 


calcRgns 

One message our altered CDEF needs to handle is calculat- 
ing the region of the control. Param for this message is inter- 
preted as a handle to a region. This is quite simple to do if your 
control is rectangular, you just make acall toRectRgn passing the 
region handle and the control’s rectangle. To be honest, a 
rounded button is not really a strict rectangle, but the corners are 
generally too small to really matter. 


testCntl 

The next message we need to handle is whether or not the 
user pressed the mouse button while in our control. We first 
check to see if our control is active and then whether or not it was 
in the indicator (we have none). Finally we call PtinRect on 
param, typecasted now to be a point, to see if we are actually in 
the control. 

If we are in the control's rectangle, we switch on con- 
trIRfCon to see which type of control was pressed. Then we 
might want to do some further testing to see what part of the 
control was pressed, such as the page up or page down regions. 
Our CDEF has only one region so we send back the message 
inButton, if it is an altered button, or inCheckbox, if it was an 
altered checkbox or radio button. 


309 


drawCntl 
I saved the largest routine for last. When we respond to a 
drawCntl message, we must draw the control with the appropri- 
ate value and hilighting. When we come in, we first check to see 
if the control is visible (no need to draw something that is 
invisible). Then we switch off the contrIRfCon field to handle 
each control type separately. 


The Button 

A normal button only shows it's state when pressed, i.e. 
hilighted. Then is goes back to normal. In my demo, I alter the 
button to not draw the title and draw a dark or light border around 
the control depending on whether it was hilighted or not. Then 
I dim the control if it is deactivated. 

You may ask yourself, where are the faces of the die? They 
are not handled by the CDEF. I did this for two reasons. The first 
was to make a semi-generic control that put up a dark outline 
when pressed and a lighter one when not. The second reason was 
to show the effects of the picture when the control is deactivated. 


The Checkbox 

This simple drawing routine puts up the control's title and 
the On/Off title, in my case Left/Right. I might want to mention 
a nice routine, TextBox. If TextEdit is initialized, this routine 
saves the hastle of left/center/right justifying by passing it the 
title, the rectangle the title is to be drawn in, and the justification 
(teJustLeft, teJustCenter, teJustRight). Next, I see if the check- 
box is on or off and draw the switch in that position with a thick 
pen or thin depending whether or not it is hilighted. 


The Radio Controls 

Although the radio controls are one type of control, each is 
drawn in a slightly different way. I first put up the title and then 
switch on contrIRfCon again to draw the traffic light box and set 
up the shade of the light. Then I draw the light according to the 
shade or override it with white if the control 15 not set. Then I dim 
the control if inactive. 

You will notice that there is not a hilighted state, other than 
inactive. You do not need to put one in if you do not feel it is 
necessary. For that matter, there is no reason why you need to 
deactivate your control by dimming it. You could dim just part, 
dim it with a different pattern, or even draw something entirely 
different. Just remember not to go overboard and try to stick to 
the standard interface (I might have drawn a thicker circle). But 
if it seems natural to draw it in a nonstandard way, go ahead; that 
is after all the purpose to this article and all those little hooks. 


Attaching Your Routine 
The code to override the standard definition with yours is 
quite simple. Make sure your window is invisible to start off with 
so that you can attach your drawing routine before QuickDraw 
draws something. Then follow the example: 


MyWindow := GetNewWindow(WindowID, NIL, Pointer(- 1); 
CDEFHandle :- NewHandle(0); (Get temporary contro! handle) 
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CDEFHandle := PtrC@myCDEFProc); (Point it to our routine) 
CtrlHdl := GetNewControl(ButtonID, MyWindow); 
HLockCHandleCCtr1Hd12); 

CtrlHdl^^.contrlDefProc := CDEFHandle; (Set to our proc) 
HUnLockCHandleCCtr 1Hd122; 

Show(MyWindow); (make it visible) 

SelectWindow(MyWindow); (bring to front) 


SetPort(MyWindow); (set the port to our window) 


Further Notes 

The die pictures are done by changing the min/max of the 
button to 0/5. When the button is pressed, the value is set 
accordingly, and the button's rectangle is invalidated. Then 
during the update event, the appropriate picture is retrieved 
according to the button's value and drawn. Then the controls are 
drawn, dimming the die face if inactive. 

There are a couple notes of warning that you should be aware 
of. The first is that you must call DisposeWindow to dispose of 
your controls. Don't just quit, or you'll crash. The second has to 
do with debugging. 

I worked this out in Lightspeed Pascal 2.0. Now I usually 
like to put a few writeln statements to the text window while 
developing. AndI did so in my CDEF to trace it being called. 
Nothing appeared in my window. My tracing showed that I was 
indeed going where I should be with all the right values. What 
was wrong? Well it was those debugging statements. I figured 
that the writeln statements were setting the port to the text 
window and notresetting the port. Therefore my control drawing 
routines were being directed to the wrong port. 


That's about it. Good luck! 


Buttons.project 


Options File (by segment) Size 
Runtime .lib 18256 "$3 


Interface .lib 8104 
[N(VYR] initTheMenus.Pas 72 
[V|[R] myCDEF pas 
[VIR] AboutDialog.Pas 


UNIT nmyCDEF ; 


INTERFACE 
FUNCTION DesignerButtonProc CvarCode : integer; 
theControl : ControlHandle; 
message : integer; 
param : longint) : longint; 
IMPLEMENTATION 


FUNCTION DesignerButtonProc; () 
(Custom controls for our controls) 
CONST 


inactive = 255; 
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indicator = 254; 
regbutton = 3; 
regcheck = 4; 
rStop = 5; 
rCaution = 6; 
rGo = 7; 


PROCEDURE DodrawCnt] CtheButton : integer; 


ControlHdl : ControlHandle; 
thePart : longint); 
VAR 
cRect, titleRect, designRect, tempRect, dimRect 
onBox, offBox : Rect; 
height, width, curve, start, 
titlewidth : integer; 
titlestr, tempstr : str255; 


PROCEDURE DeactiveButton CtheRect : rect); 
(dim the button) 
BEGIN 
PenPat(Gray); 
PenMode(PatBic); 
PaintRect(theRect); 
PenNormal; 
END; 


BEGIN (of main drawing routines) 
IF ControlHdl^^.contrlVis © 0 THEN (visible?) 
BEGIN 
HLockCHandleCControlHdl)); 
cRect := ControlHdl^*.contrlRect; 
(get the rectangle of control) 
CASE ControlHdl^^.contrlRfCon ОҒ 
(switch on button type) 
regbutton : (regular button) 
BEGIN 
PenSize(2, 2); 
curve := (cRect.bottom - cRect.top) DIV 2; 
IF ControlHd1^^.contrlHilite > Ø THEN 
(hilight button?) 
PenPat(black) 
ELSE 
PenPatCdkgray); 
FrameRoundRect(cRect, curve, curve); 
(draw button) 
PenNormal; 
IF ControlHdl^^.contrlHilite = inactive 
THEN (inactive?) 
BEGIN 
tempRect := cRect; 
InsetRectCtempRect, 2, 2); 
DeactiveButton( tempRect); 
END; 
END; 


regcheck : {checkbox} 
BEGIN 
EraseRect(cRect); 
titleRect := cRect; 
titleRect.top := titleRect.bottom - 12; 
designRect := cRect; 
designRect.bottom := designRect.bottom - 12; 
width := titleRect.right - 
titleRect.left; 
height := designRect.bottom - 
designRect.top; 


(draw control title) 

TextFontCsystemFont); 

titlewidth := StringWidthC(ControlHd]l^^ 
.contr Title); 

titlestr := ControlHdl^^.contrlTitle; 

TextBox(PointerCord(@titlestr) + 1), 


length(titlestr), titleRect, 
teJustLef t); 


(draw ON/OFF, or LEFT/RIGHT, titles) 
tempRect := designRect; 
tempRect.left := tempRect.left + 20; 
tempRect.bottom := tempRect.top + 12; 
tempstr := ‘LEFT’; 
TextBox(PointerCord(@tempstr) + 1), 
length(tempstr), tempRect, 
teJustRight); 
tempRect.bottom := designRect.bottom; 
tempRect.top := tempRect.bottom - 12; 
tempstr := ‘RIGHT’; 
TextBox(PointerCord(@tempstr) + 1), 
lengthCtempstr), tempRect, 
teJustRight); 
TextFontCapplFont?); 


(start drawing switch) 

tempRect := designRect; 

tempRect.right := tempRect.left + 40; 

WITH tenpRect DO (draw Switch) 

BEGIN 

width := right - left; 
height := bottom - top; 

onBox.top := top + (height DIV 2) - 10; 
onBox.bottom := onBox.top + 20; 

onBox.left := left + (width DIV 2) - 10; 
onBox.right := onBox.left + 20; 


IF ControlHdl^^.contrlHilite » Ø 
THEN (Hilite?) 
PenSize(2, 2) 
ELSE 
PenSizeC1, 1); 
IF ControlHdl^^.contrlValue > Ø 
THEN 
BEGIN (draw on) 
FrameArcConBox, 0, -270); 
Movelo(left + (width DIV 2), 
onBox. top); 
Line(20, -20); 
Line(10, 10); 
LineToConBox.right, top + 
Cheight DIV 2)); 
END 
ELSE 
BEGIN (draw off) 
FrameArcConBox, 90, -270); 
MoveToConBox.right, top * 
(height DIV 225; 
Line(20, 20); 
LineC-19, 10); 
LineToCleft * (width DIV 2), 
onBox.bottom); 


END; 
END; ( of with) 
END; 


rStop, rCaution, rGo : (radio button) 
BEGIN 
designRect := cRect; 
titleRect := designRect; 
titleRect.left := titleRect.left + 25; 
titleRect.top := titleRect.top + 3; 
designRect.right := designRect.left + 20; 


(draw title of control) 

TextFont(sustemFont); 

titlestr := ControlHdl^^.contrlTitle; 

TextBox(Pointer(Cord(@titlestr) + 1), 
length(titlestr), titleRect, 
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teJustLef t); 
TextFontCapplFont); 
height := designRect.bottom - 
designRect . top; 


(switch on RefCon for radio button: stop, caution, and go.. 


this is for radio button specific stuff) 


CASE ControlHdl^^.contrlRfCon OF 
rStop : 
BEGIN 
(draw box) 
PenSize(2, 2); 
MoveToCdesignRect. left, 
designRect .bottom); 
LineToCdesignRect. left, 
designRect.top); 
LineToCdesignRect right, 
designRect. top); 
LineToCdesignRect right, 
designRect.bottom); 
PenNormal; 
PenPat(dkgray); (light color) 
END; 
rCaution : 
BEGIN 
(draw box) 
PenSize(2, 2); 
MoveToCdesignRect.left, 
designRect .bottom); 
LineToCdesignRect. left, 
designRect. top); 
MoveToCdesignRect.right, 
designRect. top); 
LineToCdesignRect.right, 
designRect .bottom); 
PenNormal; 
PenPat(ltgray); (light color) 
END; 
rGo : 
BEGIN 
(draw box) 
PenSize(2, 2); 
MoveToCdesignRect. left, 
designRect. top); 
LineToCdesignRect. left, 
designRect bottom); 
LineToCdesignRect right, 
designRect .bottom); 
LineToCdesignRect.right, 
designRect. top); 
PenNormal; 
PenPat(gray); (light color) 


2 


OTHERWISE 
END; ( of case ) 


(draw light) 

onBox := designRect; 

InsetRect(onBox, 4, 4); 

onBox.left := onBox.left + 1; 

onBox.right := onBox.right + 1; 

IF ControlHdl^^.contrlValue = 0 THEN 
(override pattern if off) 
PenPat(white); 

PaintOvalConBox); 

PenNormal; 

Ғгатедуа 1 СопВох ); 


IF ControlHdl^^.contrlHilite = inactive 
THEN (deactivate control) 
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BEGIN 
tempRect := cRect; 
DeactiveButton(tempRect); 
END; 


END; 
END; (of button) 


HUnLockCHandleCContro1Hdl2); 
END; (of a visible control) 
END; 


FUNCTION DotestCnt] CtheButton : integer; 
ControlHdl : ControlHandle; 
thePoint : point) : longint; 

(Test what part of control) 

BEGIN 

DotestCnt] := 0; (initial value) 
IF ControlHdl^^.contrlHilite «€» inactive THEN 

(active control?) 

BEGIN 
IF ControlHdl^^.contrlHilite © indicator 
THEN (indicator?) 
BEGIN 
IF PtInRectCthePoint, ControlHdl^* 
.contrlRect) THEN (in control's rect) 
BEGIN 
CASE ControlHd1l^^.contr Rf Con OF 
(switch on control tupe.. here is where 
you send a code back as to what type 
of control and what part of that 
control was pressed. We only have 
controls with one part, so no further 
testing is needed) 
regbutton : 
DotestCnt] := inButton; 
regcheck, rStop, rCaution, rGo : 
DotestCnt] := inCheckBox; 


OTHERWISE 
END; 
END; 
END 
ELSE 
DotestCnt] := indicator; 
END; 
END; 


PROCEDURE DocalcCRgns CtheButton : integer; 
ControlHdl : ControlHandle; 
RegionHdl : RgnHandle); 
(calculate region of control) 
BEGIN 
(easy as pie if rectangular) 
RectRgnCRegionHdl, ControlHdl^^.contrlRect); 
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BEGIN (main proc routine) 
DesignerButtonProc := 0; (initialize the result) 


(switch on what we are to do) 
CASE message OF 
drawCnt] : 
DodrawCntlCvarCode, theControl, param); (draw) 
testCntl] : 
DesignerButtonProc := DotestCntl(varCode, 
theControl, Point(param)); (test) 
calcCRgns : 
DocalcCRgnsCvarCode, theControl, 
RgnHandle(param)); (region) 
OTHERWISE 


END; (of case) 
END; 


@ The Best of MacTutor, Vol. 5 


END. 


PROGRAM DesignerButtons; 

(Program name:DesignerButtons.Pas ) 

(Function: This is the main module for this program. ) 
(Historu: 12/19/88 Original bu Prototuper. 

( Modified 1/6/89 ) 


USES 
AboutDialog, ExampleWindow, InitTheMenus, 
HandleTheMenus; 


CONST 
sleep = 10; 
mBarHeightGlobal = $BAA; 
sBarWidth = 16; 
SuspendEvt = 15; 


VAR (Main variables) 
myEvent: EventRecord; (Event record for all events) 
doneFlag: boolean; (Exit program flag) 
code: integer; (Determine event type) 
whichWindow, MainWindow: WindowPtr; 
mResult: longint; 
theMenu, theItem: integer; 
chCode: integer; (Key code) 
ch: char; (Key pressed in Ascii) 
doIt: Boolean; (Event Loop bolean) 
tempPort: OrafPtr; 
DragArea, screen: rect; 
mBarHeight: integer; 
MemoryPtr: “Integer; 
HiByte: byte; 
bit0: LongInt; 
sysresult: boolean; 
ResumePeek: WindowPeek; 
SuspendPeek: WindowPeek; 


PROCEDURE crash; 


BEGIN 
ExitToShe11; 
; 

BEGIN (main ) 
MoreMasters; 
InitGraf(@thePort); (Quickdraw Init) 
InitFonts; (Font manager init) 
InitWindows; (Window manager init) 
InitMenus; (Menu manager init) 
TEInit; (Text edit init) 
InitDialogs(écrash?; (Dialog manager) 
FlushEventsCeveryEvent, 0); 
InitCursor; (Make an arrow cursor) 
doneFlag := FALSE; (Do not exit program yet) 
MemorgPtr := pointer(mBarHeightGlobal); 


mBarHeight := MemorygPtr^; 

Screen := ScreenBits.Bounds; (current screen device) 

SetRect(DragArea, Screen.left + 4, Screen.top + 
mBarHeight * 4, Screen.right - 4, Screen.bottom - 4); 


Init.Mg.Menus; {Initialize menu bar) 
Init_ExampleWindow; {Initialize the window ) 
Open_ExampleWindow(MainWindow); (Open the window ) 


REPEAT (main event loop) 
DoIt := WaitNextEvent(EveryEvent, myEvent, sleep, 
NIL); (no mouse tracking) 
IF DoIt THEN 
BEGIN 


code := FindWindow(myEvent.where, whichWindow); 
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(Get 


which window the event happened in) 
CASE myEvent what ОҒ 


MouseDown: {Mouse button pressed) 
BEGIN (Handle the pressed button) 
IF (code = inMenuBar) THEN 

BEGIN (Get menu selection } 
mResult := MenuSelect(myEvent.Where); 
theMenu := HiWord(mResult); ( menu) 
theItem := LoWord(mResult); (item) 
Handle.Mg.MenuCdoneFlag, theMenu, 

(һе tem); 
END; (End of inMenuBar) 


IF (code = inContent) THEN 
BEGIN (Handle hit inside a window) 
IF (whichWindow € FrontWindow) THEN 
SelectWindowC(whichWindow) 
ELSE 
BEGIN (Handle the button) 
SetPort(whichWindow); 
Do-ExampleWindow(myEvent); 
END; (End of else) 
END; (End of inContent) 
IF (code = inSysWindow) THEN 
(See if a DA selection) 
SystemClick(myEvent, whichWindow); 


IF (code = inDrag) THEN 
DragWindowCwhichWindow, myEvent.Where, 
DragArea); 


IF (code = inGoAway) THEN 
IF TrackGoAway(whichWindow, 
myEvent .Where) THEN 


BEGIN 
HideWindowCwhichWindow); 
doneFlag := true; 

END; 


END; (End of MouseDown) 
KeyDown, AutoKey: (Handle key inputs) 
BEGIN (Get the key and handle it) 
WITH nyevent DO 
BEGIN 
chCode := BitAnd(message, 
CharCodeMask); (Get character} 

ch := СНЕ(сһСоде); 
(Change to ASCII) 
IF COdd(modif iers DIV coe 


BEGIN 
mResult := MenuKey(ch); 
theMenu := HiWord(mResult); 
theItem := LoWord(mResult); 


IF CtheMenu © 0) THEN 
(See if a list was selected) 
Handle. My. MenuCdoneF lag, 
theMenu, theItem); 
END; () 
(End for with) 
(End for KeuDown,AutoKeu) 


END; 
END; 


UpDateEvt: (Update event for a window) 

BEGIN (Handle the update) 
GetPort(tempPort); 
whichWindow := WindowPtr(muEvent.message); 

(Get the window the update is for) 
SetPort(whichWindow); 
BeginUpdate(whichWindow); 
(Set the clipping to the update area) 
Update_ExampleWindow(whichWindow); 
(Update this window) 
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EndUpdate(whichWindow); 
(Return to normal clipping area) 
SetPort(tempPort); 

END; (End of UpDateEvt) 


ActivateEvt: (Window activated event) 
BEGIN (Handle the activation) 
whichWindow := WindowPtr(muevent.message); 
(Get the window to be activated) 
IF odd(muEvent.modifiers) THEN 
(Activate and not DeActivate) 
SelectWindow(whichWindow); 
(Activate the window bu selecting it) 
END; (End of ActivateEvt) 


SuspendEvt: 
BEGIN 
bit® := 31; (convert 68000 to toolbox) 
(check for resume event } 
IF Odd(myEvent .message) THEN 
BEGIN (resume) 
whichWindow := FrontWindow; 
IF whichWindow = MainWindow THEN 
BEGIN 
Setport(whichWindow); 
InvalRect(whichWindow^ .portRect); 
SelectWindowCwhichW indow); 
END; 
IF FrontWindow © NIL THEN 
BEGIN (0A check) 
ResumePeek := 
WindowPeek(FrontWindow); 
IF ResumePeek* .windowKind < Ø 
THEN (04) 
BEGIN (da) 
myEvent.what := activateEvt; 
BitSetCémyEvent . modif iers, 
bit0); 
sysresult := 
SystemEventCmyEvent ); 
END; (da) 
END; (DA check) 
( end of activate Event) 
END (of resume) 


ELSE 
BEGIN (suspend) 

(de-activate Event) 

whichWindow := FrontWindow; 

IF whichWindow = MainWindow THEN 

BEGIN 

SetPortCwhichWindow); 
InvalRectCwhichWindow^ .portRect); 


END; 
IF FrontWindow © NIL THEN 
BEGIN {DA check) 
SuspendPeek := 
WindowPeek(FrontWindow); 
IF SuspendPeek^ .windowKind < 0 
THEN 
BEGIN (da) 
myEvent.what := activateEvt; 
BitCirC@myEvent.modifiers, 
bitð); 
sysresult := 
SystemEvent(myEvent); 
END; (da) 
END; (DA check) 
END; (suspend) 
END; 


OTHERWISE 
BEGIN 
END; (End of otherwise) 


END; (End of case) 
END; (end of waitNextEvent) 
UNTIL doneFlag; (End of the event loop) 
DisposeWindow(MainWindow); 
END. (End of the program) 


UNIT InitTheMenus; 
INTERFACE 


PROCEDURE Init_My_Menus; 


VAR 
AppleMenu: MenuHandle; 
FileMenu: MenuHandle; 


IMPLEMENTATION 


PROCEDURE Init_My_Menus; (Initialize the menus) 
CONST 

; (Apple Menu resource ID) 

; (File Menu resource ID) 

BEGIN (Start of Init Му Menus) 
ClearMenuBar ; (Clear any old menu bars) 
AppleMenu := GetMenu(Menu1); (Get apple menu) 
AddResMenuCAppleMenu, ‘DRVR’); (Add in DAs} 
InsertMenuCAppleMenu, 0); 
FileMenu := GetMenu(Menu2); (File menu) 
InsertMenu(CF ileMenu, 0); 
DrawMenuBar; (Draw the menu bar) 

END; (End of procedure Init. Му Menus) 


END. (End of Unit) 
UNIT AboutDialog; 


(File name:AboutDialog.Pas  ) 
(Function: Handle a dialog) 


INTERFACE 
PROCEDURE D_AboutDialog; 


IMPLEMENTATION 
CONST (item numbers for controls in Dialog) 
I-0K = 1; 
VAR 


ExitDialog: boolean; (Flag used to exit Dialog) 
PROCEDURE 0. AboutDialog, 


VAR 
GetSelection: DialogPtr; (Name of dialog) 
itemHit: Integer; (Get selection) 


BEGIN (Start of dialog handler) 
GetSelection := GetNewDialog(2, NIL, Pointer(- 12); 
(Bring in the dialog resource) 
ShowWindow(GetSelection); (Open a dialog box) 
SelectWindow(GetSelection); (Lets see it) 
SetPort(GetSe lection); 


ExitDialog := FALSE; (Do not exit loop yet) 
REPEAT (Start of dialog handle loop} 
ModalDialog(NIL, itemHit); 
IF (ItemHit = 1-0K) THEN (Handle Button) 


BEGIN 
ExitDialog := TRUE; (Exit the dialog) 
END; (End for this item selected) 


UNTIL ExitDialog; (Handle until exit selected) 
DisposDialog(GetSelection); 
END; (End of procedure} 
END. (End of unit) 


UNIT ExanpleWindow; 


ni‘ aa 
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(File name: ExampleWindow.Pas) 
(Function: Handle a Window) 


INTERFACE 
USES 
myCDEF ; 


PROCEDURE Init. ExampleWindow; 

PROCEDURE Open_ExampleWindow (VAR theWindow: WindowPtr); 
PROCEDURE Update_ExampleWindow CwhichWindow: WindowPtr); 
PROCEDURE Do.ExampleWindow (myEvent: EventRecord); 


IMPLEMENTATION 


CONST 
I Buttonx! = 3; (Button ID) 
I-Checkboxx2 = 4; (Checkbox ID) 
I-Radio2 = 6; (Radio ID) 
I_Radio3 = 7; (Radio ID) 
I_Radiol = 5; (Radio ID) 
VAR 


MyWindow: WindowPtr; (Window pointer) 
tempRect: Rect; (Temporaru rectangle) 
CtrlHandle, buttonHdl: controlhandle; 
sTemp: Str255; (Get text entered, temp holding) 
RiControl: ARRAY[1..3] OF ControlHandle; 

( Radio button handles for group 1) 


PROCEDURE Init ExampleWindow; 
BEGIN 

MyWindow := NIL; (we are not valid yet) 
END; 


(Update our window, someone uncovered a part of us) 
PROCEDURE UpDate. ExampleWindow; 
CONST 
picBaseID = 144; 
VAR 
SavePort: WindowPtr; (Place to save the last port) 
pictRect: rect; 
Pic_Handle: PicHandle; 
pictindex: integer; 


BEGIN (Start of Window update routine) 
IF (MyWindow € NIL) AND (MyWindow = whichWindow) 
THEN 
BEGIN 
TextFont(systemFont); 
(Draw a string of text, Static Text } 
SetRect(tempRect, 266, 100, 312, 116); 
sTemp := ‘Button’; 
TextBox(PointerCord(@sTemp) + 1), length(sTemp), 
tempRect, teJustLeft); 


(Draw a string of text, Static Text ) 
setRect(tempRect, 151, 100, 217, 116); 
STemp := 'CheckBox'; 
TextBox(PointerCord(@sTemp) + 1), length(sTemp), 
tempRect, teJustLeft); 


(Draw a string of text, Static Text } 

setRect(tempRect, 36, 100, 77, 116); 

sTemp := ‘Radio’; 

TextBox(PointerCord(@sTemp) + 1), length(sTemp), 
tempRect, teJustLeft); 


(Draw a string of text, Static Text } 

SetRect(tempRect, 76, 125, 287, 141); 

STemp := ‘Designer CDEF by Kirk Chase’; 

TextBox(PointerCord(@sTemp) + 1), length(sTemp), 
tempRect, teJustLeft); 


— s vT- F son rT r+ 
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TextFont(appl]Font); 
pictRect := buttonHdl^^.contriRect; 
InsetRect(pictRect, 2, 2); 
pictindex := GetCtlValueCbuttonHd1); 
Pic-Handle := GetPicture(picBaseID + pictindex); 
(Get Picture into memoru) 
IF (Pic_Handle © NIL) THEN 
DrawPicture(Pic_Handle, pictRect); 
DrawControls(MguWindow); (Draw controls) 
END; (End for if (MyWindow<>nil)) 


END; (End of procedure) 


(Open our window and draw everything) 
PROCEDURE Open. ExampleWindow; 
VAR 


CDEFHandle: handle; 
chkhdl: controlhandle; 


BEGIN (Start of Window open routine) 
IF (MyWindow = NIL) THEN 


BEGIN 
MyWindow := GetNewWindowC1, NIL, Pointer(-1)); 
(Get the window from the resource f ile) 
theWindow := MyWindow; 


(get a handle to our CDEF Proc) 
CDEFHandle := NewHandle(@); 
CDEFHandle^ := Ptr(@DesignerButtonProc); 


{ Make a button, Button } 

CtrlHandle := GetNewControlCI.Buttonx1, 
Мун indow); 

HLockCHandleCCtrlHandle)); 
CtrlHandle^^.contrlDefProc := CDEFHandle; 
HUnLockCHandleCCtrlHandle)); 
CtrlHandle^^.contrlHilite := 255; 
buttonHdl := CtrlHandle; 


( Make a checkbox, Checkbox ) 

CtrlHandle := GetNewControlCI Checkboxx2, 
MyWindow); (Make a new checkbox) 

HLockCHandleCCtrlHandle)2); 

CtrlHandle**.contriDefProc := CDEFHandle; 

HUnLockCHandleCCtr Handle )); 

chkhdl := CtrlHandle; 


( Make a radio button, Radiol } 
RiControl(1) := GetNewControl(I_Radiol, 
Мун indow); 
HLockCHandleCCtrlHandle)); 
R1ControlL11^^.contrlDefProc := CDEFHandle; 
HUnLock(HandleCCtrlHandle)); 


( Make a radio button, Radio2 ) 
RIContro1[2] := GetNewControlCI. Radio2, 
MyW indow); 
HLock(Handle(CtrlHandle)); 
RIContro1[21^^.contrlDefProc := CDEFHandle; 
HUnLockCHandleCCtr l1Handle)); 


( Make a radio button, Radio3 ) 
RiControl(3] := GetNewControl(I_Radio3, 
MyWindow); 
HLockCHandleCCtrlHandle2); 
RIContro1(31^^.contrlDefProc := COEFHandle; 
HUnLockCHandleCCtrlHandle2); 


showW indow(MyWindow); 
SelectWindow(MyWindow); (window to front) 
SetPort(MyWindow); {write into our window) 


UpDate.ExampleWindowC(MyWindow); 
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END (End for if (MyWindowOni12) 
LSE 
SelectWindow(MuWindow); 
END; (End of procedure) 


(Handle action to our window, like controls} 
PROCEDURE Do-ExampleWindow; 
CONST 

HiliteValue = 10; 
inactive = 255; 
active = 
left = 0; 
right = 1; 


VAR 
RefCon: integer; (КеҒСоп for controls) 
code: integer; (Location of event) 
theValue: integer; (Current value of a contro!) 
whichWindow: WindowPtr; (window for event) 
myPt, myPtGlobal: Point; 
theControl: ControlHandle; 
badRect: rect; 


0; 


PROCEDURE Do_A_Button; 


BEGIN 
HiliteControl(theControl, HiliteValue); 
(Darken the button) 
RefCon := GetCRefCon(theControl); 
(get control refcon) 


CASE RefCon OF (Select correct button) 
I_Buttonx 1: (Button, button} 

BEGIN (start for this button) 
theValue := GetCtlValue(theControl); 
theValue := (theValue + 1) MOD 6; 
SetCtlValueCtheControl, theValue); 
(Set button to new value) 
badRect := buttonhdl^^.contriRect; 
InvalRect(badRect); 

END; (end for this button} 


OTHERWISE (allow other buttons, trap for debug) 
END; (end of case) 


HiliteControlCtheControl, active); 
END; (Handle a button being pressed) 


PROCEDURE Do_A_Checkbox; 
(Handle a checkbox being pressed) 
VAR 
Index: integer; (Index used for radios) 


PROCEDURE Clear iRadioGroup; 
(Routine to clear radios in group 1) 
VAR 
Index: integer; (Index used for radios} 
BEGIN (Start of the clear routine} 
FOR Index := 1 TO 3 DO (Step thru all radios) 
SetCtlValueCR1IControltIndex], 0); 
(Set this radio to zero) 
END; (End of the clear routine) 


BEGIN _ (Handle a checkbox being pressed) 
RefCon := GetCRefCon(theControl); 
theValue := GetCtlValueCtheControl); 
theValue := (theValue + 1) MOD 2; (Change value) 


CASE RefCon OF (Select correct button) 
I.Checkboxx2: (Checkbox, checkbox) 
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BEGIN (start for this button) 
SetCtlValueCtheControl, theValue); 
(Set checkbox to new value) 
badRect := buttonhd]**.contriRect; 
InvalRect(badRect); 
CASE theValue OF (left or right controls) 
left: 
BEGIN 
HiliteControl(buttonHdl, inactive); 
HiliteControl(Ri1Controlt1], active); 
HiliteControl(R1Contro1[2], active); 
HiliteControl(RiControl[3], active); 
END; 
right: 
BEGIN 
HiliteControlC(buttonHdl, active); 
HiliteControl(R1Control1L(1], inactive); 
HiliteControl(R1Control[2], inactive); 
HiliteControlC(R1Control(3], inactive); 


END; 
OTHERWISE 


END; 
END; (end for this checkbox) 


I.Rediol, I_Radio2, I _Radio3: 

(radio buttons) 

BEGIN (start for this radio button) 
Clear IRadioGroup; 
SetCtlValueCtheControl, 12; 

END; (end for this radio button) 

OTHERWISE 


END; (end of case) 
END; (Handle a checkbox being pressed) 


BEGIN (Start of Window handler) 
IF (MyWindow © NIL) THEN 
BEGIN 
code := FindWindow(myEvent . where, whichWindow); 
IF (myEvent.what = MouseDown) AND (MyWindow = 
whichWindow) THEN 
BEGIN 
myPt := myEvent.where; (Get mouse position) 
myPtGlobal := myPt; 
Global ToLocal(myPt); 
END; 
IF (MyWindow = whichWindow) AND (code = 
inContent) THEN (for our window) 
BEGIN 
code := FindControl(myPt, whichWindow, 
theControl); (Get type of control) 
IF (code ‹ 0) THEN (Check type) 
code := TrackControlCtheControl, myPt, 
NIL); (Track the control) 
IF code = inButton THEN 
Do-A.Button; (Do buttons) 
IF code = inCheckBox THEN 
Do_A_Checkbox; (Do checkboxes} 
END; (End for if (MyWindow=whichWindow)} 
END; (End for if (MyWindowOni12) 
END; (End of procedure) 


END. (End of unit) 
UNIT HandleTheMenus; 
INTERFACE 


USES 
AboutDialog, ExampleWindow, InitTheMenus; 


PROCEDURE Handle.Mg.-Menu (VAR doneFlag: boolean; 
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theMenu, theltem: integer); (Handle menu selection) 
IMPLEMENTATION 


PROCEDURE Handle_Mu_Menu; 

CONST 
L_Apple = 201; (Menu list) 
C_About = 1; 
LFile = 202; (Menu list) 
C_Quit = 1 

VAR 
DNA: integer; {For opening DAs} 
BoolHolder: boolean; (For SystemEdit result} 
DAName: Str255; (For getting DA name) 
SavePort: GrafPtr; (Save current port) 


BEGIN 
CASE theMenu OF (Do selected menu list} 


2 


L_Apple: 
BEGIN 
IF theltem = C_About THEN 
D_AboutDialog (Call a dialog) 
ELSE (Handle the DAs} 
BEGIN 
GetPort(SavePort); (Save port) 
GetItemCAppleMenu, theItem, DAName); 
DNA := OpenDeskAcc(DAName); (Open DA ) 
SetPort(SavePort); (Restore port) 
END; 
END; (of L Apple) 


L. File: 
BEGIN 
IF theItem = C.Quit THEN 
doneFlag := true; 
END; 


OTHERWISE 
BEGIN 
END; 
END; 
HiliteMenu(@); (Turn menu selection off) 
END; (End of procedure Handle. My. Menu) 


END. (End of unit) 


ЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
* 


* RMaker resource file sources. 

* File: DesignerButtons.R 

* History: 12/19/88 Original by Prototyper. 
x 


DesignerButtons .RSRC 
272 2KCBx 


Type KCBx = STR 
10,0 
CDEF Demo 1009 by Kirk Chase A0Dver 19 DEC 1989 


* Multifinder Menu for Quit Cmd 
Type mstr = STR 

File, 100 

File 

* Multifinder Quit name 

Type mstr = STR 

Quit, 101 

Quit 


Type FREF 
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CDEF , 128 
APPL Ø 


Type BNDL 
Bundle, 128 
KCBx 0 
ICN* 

@ 128 

FREF 

0 128 


Type SIZE = GNRL 
MultiFinder,-1 
H 


4800 ;; $4800 = bits 14 & 11 set 
L 

80000 ;; ( recomended) 

L 


50000 ;; ( minimum) 
E 


Type vers = GNRL 

H 

01;; byte vers # in BCD 

10;; byte vers part 2 & 3 

50;; byte release stage $50-release 
00;; bute stage of non-release 

00 00 ;; integer country 0-/5 

‚Р 

ү1.1 (05) 

Р 


CDEF Demo 1.1, @ by Kirk Chase for MacTutor 1989 


Tupe vers = GNRL 
‚ 2 
.H 
05;; byte vers # in BCD 
30;; byte vers part 2 & 3 
90;; byte release stage $50=release 
00;; byte stage of non-release 
00 00 ;; integer country 0-US 
‚Р 
V5.3 
.Р 
MacTutor Volume 5 Number 3 


x This is the definition for the DIALOG. 
x 


Type DLOG 

About ‚2 ‚;Ке$оигсе ID 

About Dialog ;,Оіа1од title 

186 87 313 411 ;;Top Left Bottom Right 
Visible NoGoAway ;,,Visible GoAway 


1 ;;ProcID, dialog def ID 
2 ;;Refcon, reference value 
2 ;;ID of item list 


* This is the DIALOG or ALERT item list. 
x 


Type DITL 
About Items ,2 ;;Resource ID 
3 ;,Number of controls in list 


Button Enabled ; ,Push button 
15 181 111 247  ;;Top Left Bottom Right 


OK ,,nessage 
StaticText jj Static text 
40 11 56 297 ;,lop Left Bottom Right 


Portions of code developed by Prototyper 


StaticText ;,9tatic text 


317 


15 6 36 307 ;;Top Left Bottom Right 
Designer СЕР by Kirk Chase For MacTutor \gD 


* This is the definition for the MENU. 
x 


Tgpe MENU 
Apple ‚201 ;;Resource ID 
V 14 ;;APPLE menu title 


About Designer CDEF ... 
(- 


File ,202 ;;Resource ID 
File ;;menu title 
Quit/Q ;;item title 


* This is the definition for the WINDOW. 
x 

Type WIND 

Kirk Chase ;4 
Example Window ;;Window title 

55 17 210 373  ;;Top Left Bottom Right 
InVisible GoAway ;;Visible GoAway 

4 ;;ProcID, Window def ID 

1 ;;Refcon, reference value 


;;Resource ID 


* This is the CONTROL item list. 
x 


Type CNTL 
Button ,3 ;;Resource ID 
Button Те for a Button 


5 246 81 332 ;;Top Left Bottom Right 


Visible ;;Initially visible 

0 ;;ProcID (Control definition ID) 
3 ;;RefCon (reference value) 

050 ;;Min Max Value 


Checkbox ,4 ;;Resource ID 

Deactivate ;;litle for a Checkbox 

5 136 80 221 ;;Top Left Bottom Right 

Visible j; Initially visible 

1 ;;ProcID (Control definition ID) 
4 ;;RefCon (reference value) 

010 ;,Min Max Value 


Radio Caution ‚б 
Caution 

2b 21 45 106 
Visible 

2 

6 

0 10 


;;Resource ID 


Radio Go ‚Т 
Go 

45 21 65 106 
Visible 

2 

7 

010 


;;Resource ID 


Radio Stop ,5 ;;Resource ID 
Stop 

5 21 25 106 

Visible 

2 

5 

011 


ж PICTs for button 

Type PICT = GNRL 

, 149 

‚Н 

008В 0007 0007 0068 0068 1101 А000 82А@ 


008С 0100 BAGS 0700 0700 6800 


0000 0000 
0066 0066 
FFFF FF54 
0158 5400 
4A00 2700 
5400 4400 
5000 2758 


Туре РІСТ 
,148 

.H 

0081 0007 
008С 0100 
0000 0000 
0066 0066 
FFFF FF54 
0158 5400 
1400 2700 
5400 2Ғ00 
ҒҒ 


Туре РІСТ 
, 147 


.H 

0077 0007 
008С 0100 
0000 0000 
0066 0066 
FFFF ҒҒ54 
0158 5400 
1400 5000 
А000 80А0 


Туре РІСТ 
, 146 

.H 

006D 0007 
008С 0100 
0000 0000 
0066 0066 
FFFF FF54 
0158 5400 
4A00 5000 


Type PICT 
, 145 

.H 

0063 0007 
008С 0100 
0000 0000 
0066 0066 
FFFF FF54 
0158 5400 
0083 FF 


Type PICT 
, 144 

‚Н 

0059 0007 
008С 0100 
0000 0000 
0066 0066 
FFFF FF54 
0158 А000 


Туре ICN! 
,128 (0) 
H 


0000 0800 
0700 0200 
0015 0015 
2F00 1400 
5058 5400 
4A00 5000 
А000 8DAQ 


= GNRL 


0007 0068 
GALS 0700 
0000 0800 
0700 0200 
0048 0015 
4A00 4A00 
2158 5400 
2F00 4200 


= GNRL 


0007 0068 
0А00 0700 
0000 0800 
0700 0200 
0015 0015 
1400 4A00 
2758 5400 
0083 ҒҒ 


= GNRL 


0007 0068 
@A00 0700 
0000 0800 
0700 0200 
0015 0015 
2-00 2Ғ00 
5058 A200 


= GNRL 


0007 0068 
0А00 0700 
0000 0800 
0700 0200 
0048 0048 
1400 1400 


= GNRL 


0007 0068 
0А00 0100 
0000 0800 
0700 0200 
0030 0030 
80А0 0083 


= GNRL 


include MulconFile 


1800 1844 
0248 BAFF 
0027 0021 
4200 2758 
2Ғ00 4A00 
5058 5400 
0083 ҒҒ 


0068 1101 
0700 6800 
1800 1844 
0248 OAFF 
0050 0027 
5000 5058 
1400 4400 
4258 А000 


0068 1101 
0700 6800 
1800 1844 
0248 QAFF 
0027 0027 
2700 5058 
4A00 4A00 


0068 1101 
0700 6800 
1800 1844 
0248 QAFF 
0027 0021 
4200 4258 
80А0 0083 


0068 1101 
0700 6800 
1800 1844 
0248 QAFF 
0050 0050 
2100 2158 


0068 1101 
0700 6800 
1800 1844 
0248 ФАҒҒ 
0042 0042 
FF 
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680A 0000 
0009 0009 
FFFF FFFF 
0700 0100 
5400 1400 
4200 5058 
4A00 1400 


А000 82A0 
680A 0000 
0009 0009 
FFFF FFFF 
0700 0100 
5400 1400 
2100 5058 
80A 0083 


А000 82А0 
680A 0000 
0009 0009 
FFFF FFFF 
0700 0100 
5400 4А00 
5000 5058 


Ай00 82A0 
680A 0000 
0009 0009 
FFFF FFFF 
0700 0100 
5400 4A00 
FF 


А000 82AQ 
680A 0000 
0009 0009 
FFFF FFFF 
0700 0100 
А000 80Ай 


А000 82A0 
680A 0000 
0009 0009 
FFFF FFFF 
0700 0100 
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Programmer's Workshop 


MPW Tools with TML Pascal II 


[Randy Leonard is currently employed by TML Systems, Inc. 
while completing his Master' s thesis in computer science at the 
University of Central Florida. His thesis involves improving the 
efficiency of several key algorithms in constructive solid geome- 
try (CSG). The thesis is written entirely with TML Pascal II and 
he uses several of his own MPW Tools to aid in his development.] 

The introduction of the Macintosh Programmer's Workshop 
(MPW) v3.0 this January requires that we revisit this program- 
ming environment and study its new and exciting features as well 
as the significant features of previous versions of the product. 
This article discusses how the MPW environment can be en- 
hanced with the addition of your own integrated programming 
tools. The type of commands introduced here are capable of 
executing in the background while running MPW v3.0. This 
capability enables you to continue your most important task in 
the foreground while such tasks as compiling and linking of 
programs occur in the background. Indeed, the tool introduced 
here may also run in the background. 


Macintosh Programmer's Workshop 

The Macintosh Programmer's Workshop is the official 
Macintosh development environment from Apple Computer, 
Inc. The MPW Shell is a complete development system for the 
Macintosh that includes, among other things, a multi-windowing 
text editor and a command processor. Also included with MPW 
is a linker, make facility, resource compiler, resource decom- 
piler, source code management system, and more. There is also 
complete online help as wellas an optional graphical interface for 
just about every command available in MPW. 

MPW has often times been accused of having a steep 
learning curve. The author believes this false accusation can be 
based upon two pretexts. The firstis due to unfamiliarity with the 
product. The second is due to the extraordinary power that MPW 
can provide its advanced users via the command line environ- 
mentand MPW's advanced command processor. The truth of the 
matter is that MPW is as easy to learn and use as any other 
programming environment if you were to utilize only those 
features found in MPW that the other programming environ- 
ments provide. 

The true beauty of MPW is found in its open architecture. 
That 1s, anyone can expand the functionality of MPW to suit his 
own needs. There exist two methods of adding new commands 
to MPW: scripts and tools. This two part article will demonstrate 
how to create new programming tools and how to fully integrate 
these tools into the MPW environment. This month's article will 
give the motivation for writing your own MPW tool and show 
how it is done. Part two, to appear next month, will demonstrate 
how to integrate the tool into the MPW's online help facility and 
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how to develop a graphical interface for the new command. 


MPW Tools 

Tools provide a method of adding commands that are not 
inherent to the MPW command processor. For example, the 
TML Pascal II compiler is an extension to the MPW environment 
and is therefore implemented as a tool. Other examples of MPW 
Tools are the canonical speller Canon and TMLPasMat. TML 
Systems, in fact, used these two tools to put the finishing touches 
on both its Source Code Library II and example programs found 
on the TML Pascal II distribution disk. Canon adjusts all 
identifiers in source code files so they have the same same 
capitalization as found in Inside Macintosh. TMLPasMat will 
format all Pascal source code files to a consistent format that you 
define. These two tools were especially helpful since program- 
ming styles of the programmers at TML Systems vary. 

However, we needed even more help in providing a consis- 
tent format for all source code files that left our office. As it turns 
out, some programmers at TML Systems prefer different fonts 
and different font sizes for their work. Some programmers would 
print their work on the laser writer reduced to 75% while others 
would print at 100%. Some prefer different tab settings and still 
others have large screens on which to edit their programs. This 
last problem could be especially annoying to our customers with 
small screens since only a small part of the window of a text file 
would appear on their screen when they opened the file. Each 
customer could easily resolve the problem by resizing the win- 
dow for his screen, but what if the window appeared off-screen 
to begin with! 

Another problem unrelated to each programmer's taste was 
the problem of USYM resources. The TML Pascal II compiler 
writes symbol table information for separately compiled units to 
the resource fork of the main unit source code file as USYM 
resources. This is perhaps a more favorable solution than 
creating separate files to hold the information as other compilers 
do. Deletinga file that contains symbol table information is easy, 
but how do you easily erase resources from the resource fork of 
a source code file? 

To solve the above problems, we developed a MPW tool that 
changed the font of MPW text files to any specified font and font 
size. Tab spacing is set to any defined value and the window is 
made to appear on any Macintosh screen with the top left corner 
slightly staggered from other windows and the bottom right 
corner extending to the bottom right of the screen. The page setup 
is reset to print at 100%. All USYM and other resources are 
optionally deleted as well. We call this tool ChangeTextRes. 
Below, we explain how to implement this tool, but first a little 
background. 
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What Every Tool has in Common 

MPW Tools are usually invoked from the command line of 
the MPW Shell. The command line of an MPW command is 
simply the line on which the MPW command exists. Parameters 
are passed to the tool by placing them on the commandline. A 
graphical interface for the tool, called the Commando, does exist, 
but is not typically used. The Commando interface for a tool is 
invoked by typing in the command name followed by the ellipses 
character (...). This character is obtained by holding the option 
key and pressing the semicolon. The implementation of a custom 
Commando interface for ChangeTextRes is discussed in next 
month’s article. 

Apple has defined several conventions for MPW Tools that 
allow them to work well together in an integrated fashion. First 
and most important is that a tool have some default behavior. 
Deviations from this default result only from options specified on 
the command line. Acommand line option is simply a parameter 
found on the command line starting with the character °-’. For 
example, the resource decompiler tool DeRez is invoked by 
typing: 


DeRez filename 


where filename specifies any resource file at all. If you wish 
only to decompile only dialog resources, you would type: 


DeRez filename -only 0100 


Now, only resources of type 'DLOG' will be decompiled. 
The behavior of the DeRez tool has been modified by the -only 
option. Many command line options may be specified, but the 
order in which they are given should never matter. 

Another rule is that tools are to run silently, they should 
require no interaction with the user to carry out its task. The only 
visual feedback from the tool should be in the form of a spinning 
cursor. The reasoning for these rules have their roots in the 
advanced capabilities of the MPW command processor. Should 
the reader wish to become a more powerful user of MPW, he is 
referred to the chapter Using the Command Language" of the 
Macintosh Programmer' s Workshop Reference. 


The Command Processor 

Each time a command is entered, the MPW command 
processor attempts to interpret it. If it is unsuccessful, the 
command processor assumes the command is either a tool, script, 
or an external application. Since we are writing a tool, we do not 
need to concern ourselves to much with the command processor, 
but there are a few features that need to be discussed. 

Before invoking an MPW tool, the command processor first 
attempts to interpret parts of the command line. Certain charac- 
ters have special meaning to the command processor. For 
example, the = (Option-x) character is a wild card character. If 
=.p is specified, the command processor will expand this to a 
sequence of filenames that end with .p. The MPW Tool never 
sees the =.p parameter. Rather, it sees the sequence of filenames 
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that match the =.p pattern! This not only increases a user's 
productivity, but also simplifies the writing of tools. 

Also allowed are special characters for I/O redirection, 
piping, and substitution of MPW Shell variables. Knowledge of 
these features are not necessary for the average MPW user. See 
the Macintosh Programmer's Workshop Reference for more 
details. 

Three file variables are predefined for MPW Tools, input 
(standard input), output (standard output), and diagnostic. As 
expected, standard input is the Macintosh keyboard. Standard 
outputis the current topmost window found in the MPW environ- 
ment as is diagnostic. 


How ChangeTextRes Works 

The underlying theory of ChangeTextRes is quite simple. 
The tool receives from the command line the name of each file it 
is to work on as well as any command line options that may exist. 
The resource fork of each MPW text file specified on the 
command line is deleted if the command option -d is also present 
on the command line. If the -d option is not specified then no 
resources of any files are ever deleted. ChangeTextRes will then 
change the file’s font, font size, and tab setting. 

If ChangeTextRes is instructed to delete the entire resource 
fork with the -d option, there will no longer be any resource 
specifying the page setup or window size and position. If a file 
has no resource for page setup or file window position, the MPW 
Shell will assume default values. The default value for window 
position is to stagger the window’s top left corner and cover the 
rest of the screen. The -d option will delete all US YM resources 
created by the TML Pascal II compiler as well. 

ChangeTextRes assumes default values of Monaco, 9 point, 
and 3 for the font, font size, and tab setting, respectively. The user 
may change these values with the command line options -f, -s, 
and -t. The -f option, followed by a font name instructs 
ChangeTextRes to use that fontname. The -s option followed by 
an integer value instructs ChangeTextRes to use the specified 
fontsize. And the -t option followed by an integer value instructs 
ChangeTextRes to use the specified tab setting. An error mes- 
sage is generated if an invalid font, a font size less than 1 or 
greater than 127, or a tab setting less than 1 or greater than 24 is 
specified. 

To use ChangeTextRes, type the command followed by all 
file names and options desired. Keep in mind the MPW Shell’s 
filename expansion capabilities discussed above. For example: 


ChangeTextRes MyProject.proj #.p 
-f Courier -s 12 -t 4 -d 


will delete all resources of all MPW text files ending with a 
.p as well as the file MyProject.proj. The font for each file is set 
to Courier 9 point and the tab setting is set to 4. 


Accessing the Command Line 
Accessing the command line parameters from within a tool 
isquite simple. The IntEnv unit defines two global variables used 
to access the command line parameters: argv and argc. The argv 
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variable is a pointer to an array of pointers to strings. Argc tells 
how many parameters exist in the argv array. The argv array 
starts at element 0 and argc is always one greater than the actual 
number of parameters found on the command line. The expres- 
sion argv^[argc] is always equal to nil. The first parameter of the 
argv array (argv^[0]^) is the name of the MPW tool itself and is 
useful for error message generation. All parameters to the tool 
are stored in argv^[1]^ to argv^[argc-1]^. Itis up to the program- 
mer to read in command line parameters and to distinguish 
between regular parameters and command line options. The 
ChangeTextRes tool contains the procedure ReadComman- 
dLine to accomplish this task. 


procedure ReadCommandL ine; 
var 


argV Index : integer; 
arg : Str255; 
begin 


if argc = 1 then SyntaxError(9, ''); 
argVIndex := 1; 
while argVIndex « argc do begin 
erg := argv^[argVIndex]^; 
if lengthCarg) © 0 then 
if arg[1] = ‘-’ then 
if lengthCarg) > 1 then 
HandleOptionCarg, argVIndex) 
else SyntaxError(8, ''); 
argVIndex := argVIndex + 1; 
end; ( while ) 


end; 


In this routine, argVIndex is used to traverse the command 
line parameters. Each time a command line option is found, the 
procedure HandleOption is called. HandleOption will read the 
option and set program global variables accordingly. Since 
options may require an additional parameter (e.g. the 
ChangeTextRes option -f, -s, and -t), HandleOption must have 
the ability to read the next parameter(s) on the command line and 
increment argVIndex accordingly. If an invalid command line 
option or invalid value corresponding to a valid option is found, 
HandleOption will generate an error and terminate the program. 


Rewriting a File's Resource Fork 

The sole purpose for ChangeTextRes is to rewrite part or all 
of a file's resource fork. Since it is intended to work only on 
Source code files, the segment of the program that effects a file's 
resource fork must first check to see if the file is of type ‘TEXT’ 
and has a creator of ‘MPS ‘ (the MPW signature). If this is so, 
ChangeTextRes will proceed to change the file's resource fork. 
Below is the segment of code that accomplishes this task. 


if C(fnderInfo.fdTgpe = ‘TEXT’) and 
(fnderInfo.fdCreator = ‘MPS ') then begin 
if gResDelete then begin 


anüSError := OpenRF(filename, vRefNum, ResRefNum); 
anOSError := SetEOF(ResRefNum, 0); 
anOSError := FSClose(ResRefNum); 

end; 


result := IEFAccess(filename, F STabInfo, gTabSize); 
result := IEFAccess(filename, F SFontInfo, arg); 
end 
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The global variable gResDelete is affected by the -d option. 
Ifthe -d option is presenton the command line, gResDelete is set 
to true, otherwise it is set to false. Only when gResDelete is true 
will all the resources be deleted. 

An MPW file's font, font size and tab setting are modified 
with calls to the IEFAccess function. This function is defined in 
the IntEnv unit. There are three parameters to IEFAccess. The 
firstis the filenameon which the routine is to operate. The second 
parameter defines which operation to perform, and the third 
provides a means of passing data to and receiving results from the 
IEFAccess routine. 

Our first call to IEFAccess sets the tab setting of a file. The 
predefined constant F STabInfo informs IEFAccess to set the 
tab of the specified file and the third parameter specifies the 
desired tab setting. The second call to IEFAccess sets the font 
and font size. The second parameter of IEFAccess is set to the 
predefined constant F SFontInfo. Apple has inadvertently 
documented that the third parameter, in this case, is a pointer to 
the new font and font size. This is not the case, rather, the upper 
word of this long integer is the font number and the lower word 
contains the font size. Both Е STabInfo and Е SFontInfo are 
defined in the IntEnv unit. 


Spinning the Beach Ball Cursor 

MPW Tools are, by convention, supposed to provide visual 
feedback to the user by displaying and spinning a cursor. By 
default, this cursor is the MPW beach ball cursor but may be any 
other cursor the programmer defines. Spinning cursors have a 
resource type of 'acur' and may be created with MPW's resource 
editor and/or resource compiler. See the appendix “Program- 
ming for the Shell Environment" in the MPW Pascal Reference 
Manual or Appendix D of the TML Pascal II Language Refer- 
ence for more details on creating and using such resources. 

All the routines related to the operation of the cursor by an 
MPW Tool are contained in the CursorCtl unit. Only two 
routines in this file are required by most tools: InitCursorCu and 
RotateCursor. 

For a tool to rotate the cursor, it must first call InitCursorCul. 
This routine has just one parameter which is a handle to an *acur' 
resource. If this parameter is nil, then the cursor defaults to 
MPW’s spinning beach ball cursor. Call this routine very early 
in the program to prevent fragmentation of the heap. 

Initializing the spinning cursor does not in itself cause the 
cursor to spin. The MPW Tool must manually spin the cursor 
itself. This may seem to be an inconvenience, but it is actually 
to your advantage. For example, a user can track progress of the 
MPW Linker by watching which way the beach ball rotates. The 
linker has three phases, each change in phase is accompanied by 
a change in direction of rotation of the cursor. 

Torotate the cursor, call RotateCursor(value) where value is 
some integer or long integer. Each time this procedure is called, 
value is added to an internal counter. When this counter is an 
even increment of 32, the beach ball is rotated. If value is 
positive, the cursor is rotated in the clockwise direction. If value 
is negative, the cursor is rotated in the counter-clockwise direc- 
tion. It is important to call RotateCursor on a frequent basis. It 
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is usually best to place this procedure callin the main loop of the 
program. 


Software Interrupts 

MPW Tools should be capable of responding to software 
interrupts known as signals. Currently, only one type of signal 
exists and that is the command-period (.). Signals have the 
capability of preempting a tool or any other MPW command. 
Tools will automatically respond to a signal but it may be 
necessary at times to prevent a signal from preempting a tool. 
Several routines in the Signal unitallow a tool to control theeffect 
a signal may have on it. ChangeTextRes does not in any way 
attempt to control a signal’s effect. 

The default actions taken by a tool in response to a signal 
are to close all open files, execute any installed exit procedures, 
and terminate the program. See the appendix “Programming for 
the Shell Environment” in the MPW Pascal Reference Manual or 
Appendix D of the TML Pascal II Language Reference for more 
details on how to install exit procedures. Also refer to these 
manuals for information on how to prevent or delay the effects of 
signals on MPW Tools. 


Returning Status Results 
There are basically three different conditions that cause 
ChangeTextRes to terminate. The first is normal termination and 


arises when ChangeTextRes has successfully completed proc- | 


essing its data. There are two abnormal termination conditions. 
One is due to invalid syntax of command line parameters and the 
other to the inability for the tool to successfully complete its task. 
In any case, when a tool returns control to the MPW Shell, it must 
inform the Shell of its termination condition. This is done by 
returning a status code. 

Defined in the IntEnv unit is the procedure IEExit. This 
procedure has one parameter of type LongInt. When a tool is to 
terminate, either normally or abnormally, it should call IEExit. 
Note that IEExit actually terminates the program. The value of 
its parameter is returned to the MPW Shell asa status code which 
by convention is zero to signify normal completion and non-zero 
to indicate abnormal termination. ChangeTextRes returns 1 to 
indicate a syntax error and 2 to indicate other errors. 


Further Reading 

This article has addressed many of the issues involved in 
writing MPW Tools, but there still remains a significant amount 
of potential yet to be realized. The chapter "Writing an MPW 
Tool" of the Macintosh Programmer' s Workshop Reference 
discusses all the issues of writing MPW Tools, and does so in 
much greater detail than presented here. The chapter "Building 
an Application, a Desk Accessory, or an MPW Tool" of the same 
reference describes the mechanics of building a tool, but this 
knowledge is not necessary if you are using the TML Project 
Manager. 

Chapter 8 of the TML Pascal II User' s Guide shows how to 
write MPW Tools as does Programming with Macintosh 
Programmer' s Workshop, by Joel West. This second book is 
highly recommended for any MPW user. Appendix D of the 
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TML Pascal II Language Reference and appendix titled “Pro- 
gramming for the Shell Environment" of the MPW Pascal 
Reference Manual give complete descriptions of the interface 
files required to create MPW Tools. 


Introduction To Cammando Interface 

An MPW tool is typically invoked from the command line. 
This method of accessing a tool is sometimes cumbersome, 
especially if you forget the command line options available for 
the given tool. The Commando offers an optional graphical 
interface to an MPW tool from which any capability of the tool 
may be accessed. This graphical interface is implemented as a 
resource of type ‘cmdo’ and any resource number. Each tool may 
have its own unique ‘cmdo’ resource, but such a definition is not 
required. If more than one ‘cmdo’ resource is specified in the 
resource fork of a tool, then the one with the lowest resource 
number is selected. The MPW tool ChangeTextRes discussed 
last month was defined without such an interface. In this half, 
the standard Commando interface and the various controls its 
dialogs support are described. The article closes with an example 
interface for the tool created last month. 


The Standard Commando Interface 

Most Commando dialogs share the same basic structure 
similar to the dialog for the MPW Search command seen in 
Figure 1. This dialog is divided primarily into three boxes. The 
first is the Options box. In this region are the controls used to 
access the various options of the command. There are numerous 
types of controls available to the designer of a Commando dialog, 
all of which are discussed in a later section. It is intended that 
every aspect of a given tool may be accessed via the controls in 
this box. Other dialog boxes, called subviews, may be accessed 
from button controls in this region to allow for a more organized 
and readable Options box. 

The middle of the dialog contains what is called the Com- 
mand box. The Command box is updated to reflect the current 
list of command line options each time a control in the Options 
box is modified. This command line may be copied into the 
clipboard using Command-C or the Edit menu. Below the 
Command box is the Help box. Clicking and holding down the 
mouse button on any control causes help information related to 
that control to be written in this box. 

Located in the bottom right corner of the dialog are two 
buttons. These two buttons are generically referred to as the 
Cancel and Do It buttons. Clicking Cancel or pressing Com- 
mand-period causes the Commando to be aborted. Clicking the 
Do It button or pressing the Enter key causes the command to be 
passed back to the MPW Shell for execution. Special results may 
be obtained, however, by holding down various modifier keys 
while pressing Enter. Holding the Option key while pressing 
Enter causes the command to be executed as well as echoed to 
MPW’s active window. Alternatively, holding the Command 
key while pressing Enter causes no command to be executed, it 
just causes control to be passed back to the Shell. Holding both 
the Option and Command keys and pressing Enter results in the 
command line being written to the active window without being 
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executed. 


Invoking the Commando 

There are three ways to invoke the Commando dialog. 
Perhaps the easiest is to type the name of the command and 
pressing Option-Enter, but this method is only available to users 
of MPW v3.0. Pressing Enter ona line containing the command 
name followed by the ellipsis (...) character will also activate the 
Commando. The ellipsis character is obtained by holding the 
Option key while pressing the semicolon (;) character. The third 
method is to type the word commando followed by the name of 
the tool to be invoked, and then pressing Enter. 

The latter method deserves special attention. Commando is 
actually an MPW tool. Typing commando and pressing Enter 
will activate this tool, which will then read the ‘cmdo’ resource 
of the tool specified on the command line and display its dialog 
interface. This method of invoking the Commando results in 
only the generated command to be written to the topmost win- 
dow, the command is never executed. 


Standard dialog box controls 
The ‘стао’ resource allows for various types of controls to 
be displayed in the Options box. Only controls supported by 
Commando may be displayed, but with the types of controls 
provided, any required functionality should be easily accom- 
plished. The controls and other items that may appear in the 
Options box include, but are not limited to: 


eCheck boxes 

«Radio buttons 

“Вохев, lines, and text titles 
*Pop-up menus 

eLists 

*Three-state buttons 

eIcons and Pictures 

*Nested dialog boxes 
*Redirecting output 

* Multiple input files 
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* Multiple directories 
«Single input or output file 
* Version number 


Thechapter Using MPW: The Basicsin the MPW Reference 
Manual contains a section detailing all the different types of 
controls allowed within a Commando dialog. The chapter titled 
Creating Commando Interfaces for Tools of the same reference 
gives complete resource descriptions for each type of control. 
Only a few types of controls and other Commando items will 
actually be described here. 


Radio Buttons 

Options that are mutually exclusive of each other are often 
presented as a group of radio buttons. The tab settings for 
ChangeTextRes are implemented as a cluster of radio buttons in 
the Commando interface defined here. Radio button groups are 
usually surrounded by a labeled perimeter to emphasize the 
grouping of the controls. The tab option was specified as a group 
of radio buttons in the ChangeTextRes Commando for example 
only. Depending upon taste, better methods probably exist for 
presenting this option. 

A cluster of radio buttons is considered a single item in the 
resource description. The Rez type definition for a radio button 
cluster is given as follows: 


case RadioButtons: 
key byte = RadioButtonsID; 
byte = $$CountOf(radioArray); /* 8 of buttons %/ 
wide array radioArray ( 


rect; /* bounds x/ 
cstring; /* title */ 
cstring; /* option returned */ 


byte NotSet, Set; /* whether button is set or not x/ 
cstring; /* help text for button */ 
align word; 


A general rule to follow when reading Rez type definitions 
such as this is that any field containing an equal sign can 
effectively be ignored by the programmer. Rez inserts values for 
such fields automatically at compile time. In this resource type 
definition, a cluster of radio buttons is defined to be an array of 
radio button elements, with each element consisting of an enclos- 
ing rectangle, title, corresponding command line option, default 
value, and a help field. A sample excerpt from the 
ChangeTextRes ‘cmdo’ resource is as follows: 


NotDependent ( ), RadioButtons ( 
( /* array radioArray: 21 elements */ 

/* (1) */ 

(40, 30, 55, 60), "1", *-t 1%, 
notSet, “Set tabs to one spaces", 

/* (2) */ 

(60, 30, 75, 60), "2", "-t 2", 
notSet, "Set tabs to two spaces", 

/* [3] */ 

(80, 30, 95, 60), "3", *-t 3", 
Set, "Set tabs to three spaces", 

/* [4] */ 

(100, 30, 115, 60), “4”, "-t 4”, 
notSet, “Set tabs to four spaces”, 
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/* 1201 */ 

(140, 170, 155, 210), “202, "-t 20", 
notSet, "Set tabs to twenty spaces", 

/* [21] */ 

(160, 170, 175, 210), “21”, *-t 21", 
notSet, "Set tabs to twenty one” 
“spaces”, 

/* array radioArrau */ 


), /* RadioButtons cluster */ 


Only one radio button should be marked as Set in the cluster, 
where the set button is defined as the default button. Ifno buttons 
are defined as set, then the first button in the list is assumed to be 
the default. Ifa particularradio button is defined to be the default, 
then its option return value (e.g. “-t 3”) is not written to the 
command line when that option is selected. 


Check Boxes 
Options to MPW tools are often Boolean flags, that is, they 
are either off or on non-exclusively of other options. Such 
options are best represented in the Commando dialog with check 
boxes. A group of related check boxes may or may not be 
surrounded by a labeled perimeter. The Rez type definition for 
check boxes is as follows: 


case CheckOption: 
key byte = CheckOptionID; 
byte NotSet, Set; /* whether button is set 


or not */ 
rect; /* bounds */ 
cstring; /* title */ 
cstring; /* option returned */ 
cstring; /* help text for button */ 


This type definition is similar to that of the radio buttons. 
There is one instance of a check box control in the 
ChangeTextRes Commando dialog. It is used to set the flag for 
deleting all resources for selected files. 


NotDependent ( ), CheckOption ( 
NotSet, 
(100, 250, 115, 425), 


“Delete resource fork", 

М-02 

“Delete all resources for the selected” 
“files” 


), 


Pop-Up menus 

There are two types of pop-up menu controls allowed in a 
Commando dialog: shadow and editable. A shadow pop-up 
menu isa field displayed as a shadowed box. Clicking inside this 
box will cause a pop-up menu to appear containing all valid 
choices for that particular field. The shadowed box is aligned 
around the current selection in the menu, and this selection is 
checked as well. This menu will behave just like the standard 
pull-down menu for the duration of the time the mouse button is 
held down. The menu will scroll vertically if required and the 
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selected menu item is placed in the menu box when the mouse 
button is released. The font control of the ChangeTextRes 
Commandois a shadow pop-up menu. The Rez definition for this 
type of resource is: 


case PopUp: 
key byte = PopUpID; 
byte Window, Alias, Font, Set; 
/* popup type */ 


rect; /* bounds of title */ 
rect; /* bounds of popup line */ 
cstring; /* title */ 

cstring; /* option returned */ 
cstring; /* help text for popup */ 


byte noDefault, hasDefault; 
/* hasDefault if first item 


is “Default Value” */ 


A shadow pop-up menu may contain one of four possible 
lists. The only one we are concerned with here is Font. If Font 
is selected as the pop-up type, then all available fonts are 
displayed in a scrollable pop-up menu. Also specified in this 
resource type definition are enclosing rectangles of the shadow 
box, the control’s title, enclosing rectangle of the control’s title, 
option returned, and help information. Also, if the last item in the 
resource definition is set to hasDefault, then the first item in the 
scrollable menu is “Default Font’. 

The shadow pop-up menu is convenient, but not always 
sufficient. If the desired value is not available in the menu box, 
then some means should exist for it to be manually entered. The 
type of control that allows a pop-up menu and edit box combined 
in one is called an editable pop-up menu. The Font Size control 
in the ChangeTextRes Commando is such a control. The re- 
source type definition for this control is as follows: 


case EditPopUp: 
key byte = EditPopUpID; 
byte Menulitle, Menultem, 
FontSize, Alias, Set; 


/* Type of editable pop-up жү 
rect; /* bounds of title ж/ 
гесі; /* bounds of text edit area */ 
cstring; /* title */ 
cstring; /* option to return x/ 
cstring; /* help text for textedit part */ 
cstring; /* help text for popup part */ 


This definition is almost identical to that for shadow pop-up 
menus. As with shadow pop-up menus, only font information Is 
discussed. When FontSize is selected as the type of menu, only 
the available font sizes for a specified font are listed. If none of 
the font sizes in the menu are desirable, then the user may type in 
his own value. 

Of special importance here is the association of this pop-up 
menu with some font. Editable pop-up menus are required to be 
made dependent on another shadow pop-up menu containing a 
list of fonts so that the control knows what font sizes to display. 
Dependent controls are not discussed in this article, but one such 
control is actually implemented. The excerpt from the 
ChangeTextRes ‘cmdo’ resource implementing two pop-up 
menus with one dependent upon the other is given below. 
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/* [3] */ 
NotDependent ( ), PopUp ( 
Font, 
(20, 250, 40, 320), 
(20, 330, 40, 450), 
“Font”, 
taf” 
“Select font specified files are” 


“ to assume”, 
hasDefault 


), 
Or ((1)), EditPopUp ( 
FontSize, 
(50, 250, 70, 320), 
(50, 330, 70, 400), 
“Font Size”, 
бе”, 
“User definable font”, 
“Select from available fonts” 


All that will be said for this instance of dependent controls 
is that the editable pop-up menu is made dependent on the 
shadow pop-up menu. If no font is selected in the shadow pop- 
up menu, then the pop-up menu part of the editable pop-up menu 
is disabled. The editable part of the control, however, is still 
active. 


Multiple Input Files 

When a tool allows more than one input file of a given type, 
then a single button control is displayed. An example of this 
would be the Files... button in Figure 2. Clicking this button will 
cause a modified version of the standard SFGetFile dialog to 
appear. This is shown in Figure 3. This dialog allows multiple 
files from various directories to be selected. All selected files are 
listed in the lower scrollable list. Files may be selectively 
removed from this list. A file filter may be applied to all files 
displayed in the upper scrollable list. 


Modifying Existing Commandos 

When creating any standard type of graphical resource, 
MPW users usually prefer ResEdit. But when it comes to fine 
tuning, the resource is decompiled to text format, modified by 
hand, and then compiled back to object code with the Rez 
compiler. ResEdit, though, does not have the capability to 
graphically create and edit Commando interfaces. Instead, the 
Commando tool for MPW v3.0 has a built in editor that allows the 
programmer to edit text labels and help messages. Controls and 
other items may be moved and resized with this editor as well. 
Unlike ResEdit, controls cannot be created, duplicated or de- 
leted. 

The process of creating Commando resources is to first 
create the resource text file. This may be done with little concern 
for where controls are actually placed in the dialog because 
resources may then be compiled to object code format with the 
MPW tool Rez. The dialog is then modified with the Commando 
editor. The modified interface may then be decompiled back to 
text for fine tuning using the DeRez tool. Figure 4 illustrates the 
interrelationships of the various tools that may be used in creating 
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ChangeTextRes , an MPW Tool that deletes MPW text file resources 


Figure 2 


a Commando interface. 

Commando’s built in editor may be activated by holding 
down the Command key immediately after launching Com- 
mando until the Watch cursor appears. This editor may also be 
invoked from the command line by adding the -modify option in 
one of the following ways: 


Commando ChangeTextRes -modify 


or 
ChangeTextRes.. -modify 


Commando may be used in two different modes once it has 
been launched with the built-in editor enabled. The first is 
Normal mode in which the interface operates as usual. The 
second is the Edit mode in which controls may be moved and 
resized. To activate the Edit mode, hold the Option key down 
while selecting a control. Continue to hold the Option key down 
while the control is selected to drag and/or resize the control. 

The Commando editor works in many ways like the ResEdit 
graphical editor. It also allows multiple controls to be simulta- 
neously selected and moved. Text labels may be edited much in 
the same way the text for an icon is changed from the Finder. 


еу Source Code 


D ChangeTentRes.p 
D ChangeTeutRes.Proj 
D ChangeTextRes.r 


ChangeTex 


Figure 3 
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Help messages as well as the size of the Commando dialog box 
may be modified as well. 

If the Commando’s Edit mode was activated at any time, 
then selecting the Cancel or Do It button to exit the dialog causes 
a Save dialog to appear. This Save dialog offers three options: 
save the resource, do not save the resource, or cancel the save 
operation and return to the Commando dialog. Saving a Com- 
mandoresource causes the original resource to be overwritten, so 
caution is advised. 


The ChangeTextRes Commando 

The resource file given at the end of this article defines the 
Commando interface illustrated in Figures 2 and 3. They were 
created using the techniques described in this paper. First, the 
resource text file was entered and compiled with Rez. Next, the 
Commando editor was invoked to align and resize all controls. 
The DeRez tool was then used to decompile the ‘стао’ resource 
back to the text given here. Assuming the filename containing 
the resource text file is called ChangeTextRes.r, the Rez com- 
mand used to compile this resource is: 


Rez ChangeTextRes.r cmdo.r -append 
-о ChangeTextRes 


The file cmdo.r contains the resource type declaration for the 
resource type 'cmdo'. This file comes with MPW and the Rez 
compiler knows where to find it. Cmdo.r may be omitted from 
this command if it is specified as in include file within the 
ChangeTextRes.r file. After the Commando editor has been used 
to move and resize fields, the following DeRez command may be 
used to obtain a text file containing the modified ‘cmdo’ re- 
Source. 


DeRez ChangeTextRes cmdo.r -only 'cmdo' 


Of course, instead of using the MPW command line, the 
Commando interface for the Rez and DeRez tools could have 
been used. Just think, using Commando to create new Com- 
mando interfaces! 

Conclusion 

Commando dialogs offer an optional graphical interface to 

MPW commands implemented as tools. They offer a means to 
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graphically select any feature of the MPW command they repre- 
sent and may result in that command being executed. Creating 
a Commando interface is as easy as creating a resource of type 
‘стао’ using Rez, DeRez, and Commando. ResEdit is not 
capable of editing ‘cmdo’ resources, but since Commando has its 
own built in editor, it does not matter. 


program ChangeTextRes; 


ChangeTextRes .p 


An MPW Tool to delete resource fork of MPW 
text files and rewrite the resource fork 
to specify a desired tab setting, font, 
and font size. 


(c) TML Systems, Inc., 1988 
All rights reserved. 


) 


uses MemTypes, QuickDraw, OSIntf, ToolIntf, 
PackIntf, PasLibIntf, 

( required for MPW Tools ) 
CursorCtl, IntEnv; 


var 
ResRefNum : integer; 
( reference number for resource fork of a given file ) 
filename : Str255; 


aStringPtr : StringPtr; 
( reference number for default drive ) 


vRef Num : integer; 

( Finder information for a given file ) 
fnderInfo : FInfo; 

( result from Mac ROM file I/0 calls ) 
anOSError : 05Егг; 

( passed to IEFAccess specifies font and font size ) 
arg : Longlnt; ( result from IEFAccess calls ) 
result : LongInt; 

i : integer; 


( Font number of specified font as returned bu GetFNum ) 


gFont : integer; 
gFontSize : LongInt; 
glebSize : LongInt; ( tab setting ) 


( delete all of file’s resources? ) 
gResDelete : boolean; 


function UpperCase(str: Str255): Str255; 
( 


Convert an alpanumeric string to all 
uppercase characters. 


var 
i: integer; 
begin 
for i := 1 to length(str) do 
if Cstrlil >= 'a^) and 
(str[i] <= 727) then 
str[i] := chrCord(str[il]) - 32); 
UpperCase := str; 
end; 
procedure SyntaxErrorCerr: integer; msg: Str255); 
Display the appropriate syntax error and 
then exit from the program. Return a 
status value of 1 indicating an early 
termination of program. 


begin 
case err of 
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1: writelnC'* “ msg,’ is an invalid option’); end 
2: writelnC'* missing font’); else SyntaxError(4, 4; 
3: writelnC'8 missing font size’); end 
4: writelnC'* missing tab setting’); else if str = 'D' then 
5: writelnC'* “ msg,’ is an invalid font’); gResDelete := true 
6: writelnC'* ', msg,’ is an invalid font size’); else SyntaxError(1, str); 
T: writelnC'* “ msg,’ is an invalid tab size’); end; 
8: writeln(”8 the - character must be 
accompanied by an option’); "dian SkipOptionCopt: Str255; var argIndex: integer); 
9: begin 
writelnC'* Usage - ChangeTextRes [name.] “); This routine is called only after the 
writelntC' -f fontname 8 set command line parameters have already been 
font of files to fontname’); scanned once using HandleOption. The 
writelnC* -s fontsize # set purpose of this routine is to properly 
font size of files to fontsize^); increment argIndex according to the 
writeln(' -t tabs 8 set appropriate command line options. 
tab setting to tabs’); ) 
end; 
otherwise var 
writelnC'fatal error 8”, err); str: Str255; 
end; 
IEExitC 1); ( return error status of 1) begin 
end; str := UpperCase(opt); 
Delete(str, 1, 1); (delete the ‘-’ character) 
procedure HandleOptionCopt: Str255; if str = 'F^ then ( set font ) 
var argIndex: integer); argIndex := argIndex + 1 
( else if str = 'S^ then ( set font size ) 
Set the appropriate global flag for each argIndex := argIndex + 1 
command line option encountered on the else if str = ‘T’ then ( set tab size ) 
command line. If an invalid argIndex := argIndex + 1 
option is found, give an error message and else if str = ‘D’ then ( nothing ) 
exit from the program. If the option end; 
requires an additional command line 
parameter (e.g. -f Monaco), then retrieve procedure ReadCommandL ine; 
the option(s) needed and increment the 
argIndex counter appropriately. var 
) argV Index : integer; 
arg : $tr255; 
var 
NumString, str : $tr255; begin 
if argc = 1 then SyntaxError(9, ''); 
begin argVIndex := 1; 
str := UpperCaseCopt); while argVIndex < argc do begin 
Delete(str, 1, 1); (delete the ‘-’ character) arg := ergv^[argVIndex]^; 
if str = 'F^ then begin ( set font ) if lengthCarg) © 0 then 
argIndex := argIndex + 1; if arg[1] = -” then 
if argIndex < argc then begin if lengthCarg) > 1 then 
GetFNumCargv^ largIndex]1^, gFont); HandleOptionCarg, argVIndex) 
if gFont < 0 then else SyntaxError(8, ‘’); 
syntaxError(5, argv^l[argIndex1^); argVIndex := argVIndex + 1; 
end end; ( while ) 
else SyntaxError(2, ''); end; 
end 
else if str = 'S^ then begin ( set font size ) procedure ReportError(error: integer; filename: Str255); 
argIndex := argIndex + 1; 
if ergIndex < argc then begin Generate the appropriate error message 
StringToNumCargv^ [argIndex)^, gFontSize); then exit from the program. Return a 
if CgFontSize <= 0) or status value indicating early termination 

(gFontSize >= 128) then begin from the program. 

NumToString(gFontSize, NumString); ) 
SyntaxError(6, NumString); 
end; begin 
end if error = @ then 
else SyntaxError(3, ‘’); exit(ReportError?; 
end 
else if str = ‘T’ then begin ( set tab ) writeCdiagnostic, “ERROR! ‘); 
argIndex := argIndex + 1; case error of 
if argIndex < argc then begin -35: writeln(diagnostic, filename,’ volume does not exist’); 
StringToNumCargv^ [argIndex]^,gTabS ize); -36: writeln(diagnostic, filename,’ IO Error’); 
if CgTabSize <= 0) or -37: writelnCdiagnostic, filename, 

(glabSize >= 25) then begin ‘ is a bad filename or volume name’); 
NumToStringCgFontSize, NumString); -42: writeln(diagnostic, Too many files open’); 
syntaxError(7, NumString); -43: writeln(diagnostic, filename, ‘ not found’); 

end; -45: writeln(diagnostic, filename,’ is locked’); 
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-46: writeln(diagnostic, filename, 
' is locked by a software flag’); 
-47: writeln(diagnostic, filename, 
is busy; one or more files are open’); 
-53: writeln(diagnostic, filename, ' volume not on-line’); 
-54: writeln(diagnostic, filename, 
‘ cannot be opened for writing, file is locked’); 
-61: writeln(diagnostic, filename, 
‘ Read/write permission doesn’’t allow writing’); 
otherwise 
writeln(diagnostic, ‘0S error 8”, 
error, ' has occurred. ^); 
writeln(Cdiagnostic,^ Reference Inside 
Macintosh pp. III:205-209 for further details’); 
end; 
IEExitC2); 
end; 


begin (main program) 
( make first stmt toavoid heap fragmentation ) 
InitCursorCt](ni1); 
InitFonts; (so we can read in font names) 


( so we read in JUST the font names! ) 
SetResLoad(Cfalse); 


( Set default values ) 
gResDelete := false; 
gFont := 4; 

gFontSize := 9; 
glabSize := 3; 


ReadCommandL ine; 
arg := gFont; 
arg := BSLCarg, 16); 


arg := arg + gFontSize; 

anOSError := GetVolCaStringPtr, vRefNum); 

if enOSError o @ then 
ReportErrorCanOSError, aStringPtr^2; 


L := 4; 

while i < argc do begin 

Make cursor rotate each time through loop ) 
RotateCursor(32); 
filename := агам” (115; 


~~ 


if lengthCfilename) = Ø then begin 
і = 1+]; 

сус1е; 

епа; 


if filename[1] = ‘-’ then 
SkipOption(filename, i) 
else begin ( valid filename ) 


an0SError := GetFInfo(filename, vRefNum, fnderInfo); 
if anOSError © 0 then begin 
ReportErrorCanOSError, filename); 
cycle; 
end 
else begin (file exists ) 
if K(fnderInfo.fdTgpe = ‘TEXT’) and 
(fnderInfo.fdCreator = ‘MPS ') 
then begin 
if gResDelete then begin 


anOSError := OpenRF(filename, vRefNum, ResRefNum); 
anOSError := SetEOF(ResRef Num, 0); 
anOSError := FSClose(ResRef Num); 

end; 

result := IEFAccess(filename, F STabInfo, gTabSize); 

result := IEFAccess(filename, F.SFontInfo, arg); 

end 
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else 


writelnC'WARNING! “, filename, ' is not an MPW text 
file, resources not deleted’); | 


end; (file exists 


) 


end; ( valid filename ) 


i := i+ l; 


end; ( while i < argc ) 


writeln; 


SetResLoad(true); 


IEExit(0); ( Normal status return ) 


end. (main program) 


/* 
ChangeTextRes.r 


This file contains only one resource which 
defines the commando interface for the MPW 


Tool ChangeTextRes 
*/ 


#include °стдо.г” 


resource ‘стао’ (128, “ChangeTextRes”) ( 
{ /* array dialogs: 2 elements */ 


300, 
"ChangeTextRes, an 


MPW Tool that” deletes 


“MPW text file resources", 
( /* array itemArray: 3 items */ 


/* [1] */ 


NotDependent ( ), 


RadioButtons ( 


( /* array radioArray: 21 elements */ 


/* [1] */ 


(40, 30, 55, 60), “1”, “-t 1”, 


notSet, "Set tabs 
/* [2] */ 


to one spaces", 


(60, 30, 75, 60), “2”, “-t 2”, 


notSet, “Set tabs 
/* [3] */ 


to two spaces’, 


(80, 30, 95, 60), "3", "-t 3”, 


Set, "Set tabs to 
/* [4] */ 
(100, 30, 115, 

notSet, "Set tabs 
/* [5] */ 
(120, 30, 135, 

notSet, "Set tabs 
/* [6] */ 
(140, 30, 155, 

notSet, "Set tabs 
/* (7) */ 
(160, 30, 175, 

notSet, "Set tabs 
/* [8] */ 


three spaces", 
60), *4", "-t 4", 
to four spaces", 
60), 45”, *-t 5", 
to five spaces", 
60), *6", *-t 6", 
to six spaces", 
60), *1*, *-t 7%, 
to seven spaces", 


(40, 100, 55, 140), “8”, “-% 8”, 


notSet, “Set tabs 
/* [9] */ 


to eight spaces”, 


(60, 100, 75, 140), "9^, “-% 9”, 


notSet, “Set tabs 
/* [10] */ 


to nine spaces”, 


(80, 100, 95, 140), "10", “-t 10”, 


notSet, “Set tabs 
/* (11) */ 


(100, 100, 115, 


notSet, “Set tabs 
/* (12) */ 


(120, 100, 135, 


notSet, “Set tabs 
/* [13] */ 


(140, 100, 155, 


notSet, “Set tabs 
/* [14] */ 


(160, 100, 175, 


notSet, "Set tabs 
/* (15) */ 


to ten spaces", 


140), “112, "-t 11^, 
to eleven spaces", 


140), “122, *-t 12^, 
to twelve spaces”, 


140), "13", "-t 13", 
to thirteen spaces", 


140), “14%, *-t 14", 
to fourteen spaces", 
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(40, 170, 55, 210), "15^, "-t 154, * assume", 


notSet, "Set tabs to fifteen spaces", hasDefault 
/* [16] */ ), 
(60, 170, 75, 210), “162, “-t 16”, Or ((1)), EditPopUp ( 
notSet, “Set tabs to sixteen spaces", FontSize, 
/* (17] */ (50, 250, 70, 320), 
(80, 170, 95, 210), "17", “-t 17%, (50, 330, 70, 400), 
notSet, "Set tabs to seventeen spaces", "Font Size", 
/* [18] */ бес, 
(100, 170, 115, 210), “182, “-t 182, “User definable font”, 
notSet, “Set tabs to eighteen spaces”, “Select from available fonts” 
/* [19] */ ), 
(120, 170, 135, 210), "19^", *-t 19", NotDependent ( ), MultiFiles ( 
notSet, "Set tabs to nineteen spaces", *Files..^, 
/* [20] */ "Select files who's resources are to” 
(140, 170, 155, 210), "20", "-t 202, * be deleted", 
notSet, "Set tabs to twenty spaces", (155, 350, 175, 450), 
/* (21) */ 42 
(160, 170, 175, 210), "21", “-% 21”, к”, 
notSet, “Set tabs to twentu опе spaces”, MultiInputFiles ( 
) /* array radioArrau */ (text), 
), /* RadioButtons cluster */ e 
ws 
2 
NotDependent ( ), TextBox ( ## 
grau, ) 
(30, 20,185, 220 ), ), 
“Tab Setting” NotDependent ( ), CheckOption ( 
), NotSet, 
(100, 250, 115, 425), 
/* [3] */ "Delete resource fork", 
NotDependent ( ), PopUp ( 7-04; 
Font, “Delete all resources for the selected" 
(20, 250, 40, 320), *f iles" 
(20, 330, 40, 450), ) 
"Font", ) /* array itemArray */ 
421% ) /* array dialogs */ 27) 
“Select font specified files are to” ); 222 


— 
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Advanced Mac ing 


The Notification Manager 


Hey You: The Mac Notification Manager 

More and more, code is being written for the Macintosh that 
runsin a multitasking environment. At first, an application only 
had to share space with Desk Accessories. Then came MultiFin- 
der, and multiple applications started running at the same time. 
Along the way, Macintosh programmers started creating various 
low level routines to do tricks with the machine (INITs that load 
routines into system memory, vertical retrace routines, time 
manager ‘wakeup’ routines, redirection of normal traps, etc.). At 
any given time, half a dozen or more code segments may be 
running in addition to a single ‘normal’ application. 

These code segments have to work in a very restrictive 
environment. Some are not allowed access to global data. Many 
can not make Toolbox calls that move or purge memory. Others 
can not even have control of the CPU for longer than a tick (60th 
second). Even a normal application cannot place an alert where 
the user can see it if it is running in the background under 
MultiFinder. How can these code segments inform the user of 
some event or action with these limitations? 

Enter one of newest Toolbox managers from Apple; the 
Notification Manager. The Notification Manager allows the 
code to post a notification request that, in some method, notifies 
the user of something. A Notification Request can consist of an 
Alert Notification (displaying a text message), an Audible Noti- 
fication (playing a ‘snd’ sound), an Icon Notification (displaying 
a small icon, or ‘SICN’, in the upper left corner on top of the 
Apple icon) or some combination. 

Using the Notification Manager, a terminal program run- 
ning in the background can inform the user when a download is 
complete. No matter what is running at the time, when the 
request is processed, the Notification Alert will appear on top of 
all windows. Using the Manager, an Appletalk Mail program 
could inform the user of new mail with a flashing mail box icon. 

The Notification Manager handles the processing of all 
requests (playing the sound, clicking on the alert, flashing the 
icon, etc.) asynchronously. The code segment would use two 
new Toolbox traps to inform the manager of a request. Neither 
of these two calls process the request, they simply add or detach 
records from the Notification Manager list. Because of this, they 
neither move nor purge memory, and can be safely called at any 
time, even inside of a low level interrupt procedure. 

The Notification Manager was implemented in the System 
Software 6.0. The new Toolbox traps will not function on 
systems prior to 6.0. Portions of the System Software 6.0 already 
uses the Notification Manager. By flashing a small Clock icon, 
The Alarm Clock use the manager to signal that the alarm has 
gone off. The Print Monitor also uses the Notification Manager 
to signal printing information. 


330 


Steven Sheets 


Contributing Editor 
Haufman Estates, IL 
System Volume 5, Number 5 


The Notification Manager 

The Notification Manager maintains a queue (list) of re- 
quests that need to be processed. Whenever SystemTask or 
WaitNextEvent is called, the Notification Manager checks the 
queue for an unprocessed request. First the Notification Request, 
if there is one, is processed, then the response routine, if there is 
one, is called. The response routine can be the default routine 
(simply removes the request record from the queue) or the code 
segment can define it’s own response routine to do whatever it 
wants. 

The Notification Request is a standard Macintosh Queue 
record expanded for the Notification Manager. The record has 
the following format: 


NMRec = record 
qLink: QElemPtr; 
qType: INTEGER; 
nmF lags: INTEGER; 
nmPrivate: LONGINT; 
nmReserved: INTEGER; 
nmMark: INTEGER; 
nmSIcon: Handle; 
nmSound: Handle; 
nmStr: StringPtr; 
nmResp: ProcPtr; 
nmRefCon: LONGINT; 

end; 


The qLink pointer points to the next request in the linked list 
and should not be changed by the code segment. Neither should 
the nmPrivate or nmReserved elements be changed by the code; 
the manager handles them. The qType (type of queue) of a 
Notification Queue is the value 8, the integer value of 
ORD(nmType). The qType element needs to be set to 8 before 
the request is added to the queue. 

The nmStr pointer points to the text message that would be 
displayed by the Notification Manager in an alert. If the pointer 
is set to nil, no alert will be displayed. The nmSound is a handle 
to a sound record (ie. ‘snd ‘ resource). The Sound Manager will 
play it before the alert is displayed. If nmSound is set to -1, the 
“System Error” sound is used. If it is set to 0, no sounds are 
played. The пт$1соп is the handle to the small icon (32 bytes, 
16 by 16 pixel bitmap) that the Notification Manager will flash 
in the upper left corner of the screen on top of the Apple icon. 
Usually this small icon is stored as a resource of type 'SICN'. A 
nil value for nmSIcon signifies no flashing icon. The nmMark 
element indicates who generated the notification event. An 
application should set nmMark to 1. When under MultiFinder, 
a diamond mark will be placed in the Apple menu next to the 
application's name. If the request was generated by a Desk 
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Accessory, nmMark should be set to the refNum of the DA. This 
will place a diamond mark nextto ће DA’sname. Allothertypes 
of code segments (Drivers, patches, etc.) should set this value to 
0. 

The nmResp is the pointer to the procedure called after the 
request is processed. If nmResp is set to 0, no procedure is called. 
If it is set to -1, a special response routine is called that removes 
that request from the queue. This response routine does not 
dispose of any memory (the string, the sound, the icon, or the 
request itself). If the code segment wants to define it's own 
response routine, nmResp is set to the pointer of that routine. In 
most cases (main exception is Icon Alerts), the response proce- 
dure should remove the request from the queue immediately. The 
response procedure has the following format: 


PROCEDURE MyResponse (nmRegPtr : QElemPtr) ; 


The response routine will be called by the Notification 
Manager during a SystemTask or WaitNextEvent call. Thus it is 
safe to move or purge memory. It is also safe to do any I/O (file, 
resource, serial, Appletalk). If the routine is suppose to change 
some global variables of an application, it must first make sure 
that the A5 is correct. For example, when under MultiFinder, the 
notification may occur when some other application's AS is set. 
The nmRefCon may come in handy to store the value of A5. The 
nmRefCon element can be used by the code segment for what 
ever purpose the code segment wants. A handle to a data 
structure, a pointer to a Boolean flag, or the correct A5 value 
could be stored there. | 

Apple states that the response routine should not do “user 
interface" type of drawing. Instead the routine should set a flag 
so that the application knows when it should do the drawing. To 
change a Boolean flag, it is simpler to stuff a pointer to the flag 
into nmRefCon than it is to change A5 back and forth. 


Using the Notification Manager 

There are only two routines that exercise the Notification 
Manager, NMinstall and NMRemove. NMlInstall is passed the 
pointer to the notification request that is to be installed into the 
queue. It returns noErr (0) if successful. NMRemove is passed 
a pointer to a notification request already installed in the queue. 
If it is successful in removing that request, it returns noErr also. 
Unless a request wants an Icon to be flashed for awhile, the 
NMRemove routine should be called after a notification request 
has been processed. Both calls are register based. The following 
are the Inline Glue routines needed to use the call from Pascal and 
the Assembler information: 


FUNCTION NMInstall (nmRegPtr : 
inline $205F, $A05E, $3E80; 


QElemPtr) : OSErr; 


-MMInstall C§AQ5E) 
On entry: A@pointer to the NMRec 
On exit: DÜresult code 


FUNCTION NMRemove (nmRegPtr : 
inline $205F, $A05F, $3E80; 


QElemPtr) : OSErr; 
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— NMRemove (С $AQ5F ) 
On entry: ABpointer to the NMRec 


On exit: DÜresult code 


The Sample Program: HeyYou 

HeyYou uses the Notification Manager to show 3 different 
effects. The NotifStr routine demonstrates the simplest effect, 
displaying a text message to the user. The routine uses two global 
variables, a string to hold the text, and a NMRec to hold the 
notification request. The request nmResp is set to -1 so that the 
Notification Manager will automatically remove this request 
from the queue after it has been done. Since the data is stored in 
global variables, no other clean up has to be done. 

The NotifSnd routine demonstrates a slightly more involved 
request. It plays a sound (‘snd ' resource) and displays a text 
message. No global variables are used in this example. Instead 
memory is allocated to hold the request and the test string. The 
nmResp is set to a pointer to the MySndResponse so that when 
the request is done, the MySndResponse routine can be called. 
MySndResponse can remove the request from the queue, release 
the sound from memory, dispose of the memory holding the 
string, and finally dispose of the memory holding the request 
itself. 

The method used in NotifSnd works well for code segments 
that have no access to global memory space such as Desk 
Accessories, INITs, etc. This method also has the additional 
advantage of allowing more than one request to be added at the 
same time. This could not be done with NotifStr since each 
request shared the same global variables. As long as MySndRe- 
sponse is locked in memory somewhere, the method used in 
NotifSnd will work. 

The last example, NotifIcon, demonstrates the use of icons 
by the Notification Manager. It displays a text message, blinks 
a small icon in the upper left corner of the screen and marks 
HeyYou as the application that caused this request. Usually the 
code segment wants the icon to flash in the corner until the user 
has done something in response. For example, the Alarm Clock 
does not remove it's icon until the alarm is turned off. To keep 
the Icon in use until the appropriate time, the notification request 
can not be removed from the queue or the flashing effect would 
be lost. Thus no response routine is specified. Instead the 
application removes the request (and flashing icon) when the 
application quits, when it resumes after a switch under MultiFin- 
der, or when the user selects the "Remove Icon" menu item. In 
HeyYou, one example sets a timer going so that NotifIcon is 
processed 60 seconds after the menu item is selected. Since 
HeyYou and the timer work in the background under MultiFin- 
der, this will demonstrate how the Notification Manager works 
when some other application is running. Notice the mark that 
appears next to the program name Hey You in the Apple menu. 


Beyond... 
Here are some last ideas for Notification Manager routines/ 
utilities that can be written: 
1)An example that places a Notification Request in low 
System memory, and starts a Timer routine that will install the 
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request sometime in the future. The response routine is set so that 
it removes the request and releases the memory used by every- 
thing (string, request, timer routine, response routine). With this 
routine, a “Smart” Alarm Clock would be easy to create. 

2)An Appletalk socket completion routine that automati- 
cally adds a request whenever someone sends a packet to that 
computer. If this socket is loaded into low memory, it would 
create a simple pager utility. 

3)A routine that would install an Icon Notification request, 
then set up a timer so that the request (and icon) would be 
automatically removed a few moments later. 


Listing: HeyYou.pas 

{ HeyYou program for MacTutor by Steve Sheets} 

( Demonstrates uses of the Notificaiton Manager. 
some simple String Notifications, some Sound } 

{ Notifications, some Small Icon Notifications Cimediately 
and after a delau).) 


Creates 


program HeyYou; 
( Resource Constants. ) 
const 

SICNdiamond = 0; 
SICNheyyou = 500; 
SNDbeep = 1; 
SNDclick = 2; 
SNDbong = 3; 
SNDmonkey = 4; 
ALERTabout = 500; 


( Notification Manager Queue Record. } 
type 

NMRec = record 
qLink: QElemPtr; 
qType: INTEGER; 
nmFlags: INTEGER; 
nmPrivate: LONGINT; 
nmReserved: INTEGER; 
nmMark: INTEGER; 
nmSIcon: Handle; 
nmSound: Handle; 
nmStr: StringPtr; 
nmResp: ProcPtr; 
nmRefCon: LONGINT; 

end; 
NMPtr = ^NMRec; 


( Program Global Variables. 
Strings and Flags. ) 
var 

myM1, myM2, myM3: MenuHandle; 
StrRec, IconRec: NMRec; 
StrStr, IconStr: Str255; 
doneFlag, IconFlag: BOOLEAN; 
Timer: LONGINT; 


Menus, Notification Requests, 


( Notification Manager Glue rotines. ) 

( Install Notifiaction Request into Queue.) 
function NMInstall CnmRegPtr: QElemPtr): OSErr; 
inline 

$205F, %А05Е, $3E80; 

( MOVE.L С5Р)+,А0 ) 

( -NMInstall 

( MOVE.WD@,(SP) ) 


( Remove Notifiaction Request into Queue. ) 
function NMRemove (nmReqPtr: QElemPtr): OSErr; 
inline 

$205F, %А05Ғ, $3F80; 
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( MOVE.L (SP)+,A0) 
( _NMRemove ) 
( MOVE.W DØ, CSP) ) 


(Checks to see if this is System 6.0 or above} 
function CheckSystem: Boolean; 
var 
theWorld: SusEnvRec; 
begin 
if SusEnvirons(1, theWorld) = noErr then 
CheckSustem := (theWorld.systemVersion >= $0600) 
else 
CheckSustem := FALSE; 
end; 


e 


Display About Info. ) 
procedure DoAbout; 
var 
dummy: INTEGER; 
begin 
dummy := AlertCALERTabout, nil); 
end; 


( First Test of Notification Manager. } 
Displays a simple String. The Notification Request is 
automaticallyremoved after it is completed. ) 
procedure NotifStr (St: Str255); 
var 
E: OSerr; 
begin 
with StrRec do 
begin 
(Туре := 8; 
( No Mark, Icons or Sounds. ) 
nmMark := Ø; 
nmSIcon := nil; 


nmSound := nil; 
( This String. ) 
StrStr := St; 


nmStr := @StrStr; 
( Automatically Removed when Completed. } 
nmResp := POINTERC- 1); 
nmRefCon := 0; 
end; 
E := NMInstall(ëStrRec); 
end; 


( Call bu Notification Manager after a Sound Notification has 
been completed. Removes ) 
the entru from Notification queue, releases SND resource 
if there is one, disposes of ) 
( string handle if there is one and disposes of the request 
record. ) 
procedure MySndResponse (nmReqPtr: QElemPtr); 
var 
aPtr: NMPtr; 
E: OSErr; 
begin 
aPtr := NMPtr(nmRegPtr?; 
E := NMRemove(nmReqPtr); 
if CaPtr^.nmSound € nil) and CaPtr^.nmSound € POINTERC- 
12) then 
ReleaseResourceCaPtr^ .nmSound); 
if aPtr^.nmRefCon O 0 then 
begin 
HUnLock CHandleCaPtr^ .nmRefCon)); 
DisposHandleCHandleCaPtr^ .nmRefCon)); 
end; 
DisposPtr(Ptr(nmRegPtr)); 
end; 


( Second Test of Notification Manager. ) 
( Displays a String and plays a sound. 


Allocates memmory 
for the request record and the string.) 
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( If Sound is -1, the Sustem Beep is used. Anu other 
number, indicates a SND resource, and) 
( that resource is loaded in. MuSndResponse is setup so 
that it will be called after Notification is completed.) 
procedure NotifSnd (St: Str255; Sn: INTEGER); 
var 
E: OSerr; 
tempRec: NMPtr; 
StrHdl: StringHandle; 
begin 
tempRec := NMPtr(NewPtr(SIZEOF(NMRec))); 
with tempRec^ do 


begin 
qlupe := 8; 
( No Marks or Icons. ) 
nmMark := Ø; 


nmSIcon := nil; 
( Sustem Beep or SND resource. ) 
if (Sn = -1) then 
nmSound := POINTERC- 1) 
else 
nmSound := GetResource(’snd ', Sn); 
( If String, allocate memmory for it.) 
if St = '^ then 
begin 
nmStr := nil; 
nmRefCon := 0; 
end 
else 
begin 
StrHdl := NewString(St); 
HLockCHandleCStrHdl2); 
nmRefCon := ORD4(StrHd1); 
nmStr := StrHdl^; 


end; 
( Call MySndResponse to remove resource when completed. ) 
nmResp := @MySndResponse; 
end; 
E := NMInstal1(QElemPtr(tempRec)); 
end; 


( Third Test of Notification Manager. } 
( Displays a String, displays a Small Icon and Marks the 
Current Application.) 


( This Notification is not removed until the User selects 


“Remove Icon” } 
( fromt the Menu or the Application is Quit. } 
procedure NotifIcon (St: Str255; IC: INTEGER); 
var 
E: OSerr; 
begin 
if not IconFlag then 
begin 
IconFlag := TRUE; 
with IconRec do 


begin 
qlupe := 8; 
( Current Application is Marked Cin MultiFinder).} 
nmMark := 1; 


( Small Icon is used. } 
nmSIcon := GetResourceC'SICN', IC); 
{ No SND. ) 
nmSound := nil; 
( This String. } 
( Use String Cif апу).) 
if St = '^ then 
nmStr := nil 
else 
begin 
IconStr := St; 
nmStr := eIconStr; 
end; 
( No Completion Routine.) 
nmResp := nil; 
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nmRefCon := 0; 
end; 
E := NMInstallCéIconRec); 
end; 
end; 


( If an small Icon is still flashing, Removes it and releases 
SND resource.) 
procedure RemoveNotif Icon; 
var 
E: OSerr; 
begin 
if IconFlag then 
begin 
IconFlag := FALSE; 
E := NMRemove(@IconRec); 
if IconRec.nmSIcon O nil then 
ReleaseResource(CIconRec.nmSIcon); 
end; 
end; 


( Normal Mac Setup Procedure ) 
procedure SetUp; 


begin 
doneFlag := FALSE; 
IconFlag := 
Timer := 0; 
9-1 
S[1] := CHRCapplemark); 
myMi := NewMenu( 181, S); 
AppendMenu(muM1, ‘NotifTest Source;(-^); 
AddResMenu(muM1, ‘DRVR’); 
InsertMenu(muM1, 0); 
myM2 := NewMenu(102, ‘File’); 
AppendMenu(myM2, ‘Quit’); 
InsertMenuCmyM2, 0); 
myM3 := NewMenuC 103, ‘Simple’); 
AppendMenu(myM3, ‘String Test #1;String Test #2;(-;Bong 
sound Test;Click Sound Test;Bong and Click Sound Test’); 
AppendMenu(myM3, ‘Monkey Sound Alone Test - no 
alert;System Error Sound Test;(-;Diamond Icon Test’); 
AppendMenuCmyM3, 'HeyYou Icon Alone Test - no 
alert;Delayed Icon Test;Remove Icon’); 
InsertMenuCmyM3, 0); 
DrawMenuBar ; 
end; 


( Normal Mac Menu Command Routine. ) 
procedure DoCommand (mResult: LONGINT); 
var 
theItem: INTEGER; 
theMenu: INTEGER; 
tempStr: Str255; 
tempInteger: INTEGER; 
tempLong: LONGINT; 
begin 
theItem := LoWord(mResult2); 
theMenu := HiWord(mResult); 
case theMenu of 
101: 
if theltem = 1 then 
DoAbout 
else 
begin 
GetItemC(myM1, theItem, tempStr); 
tempInteger := OpenDeskAccCtempStr); 
end; 
102. 
if theltem = 1 then 
doneFlag := TRUE; 
103: 
case theltem of 
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1: 
NotifStr('This is a String Test of the Notifica- 
tion Manager. ^); 

2: 


begin 
GetDateTimeCtempLong); 
IUTimeStringCtempLong, TRUE, tempStr); 
tempStr := CONCATC'This is another String Test 
of the Notification Manager. The Time is ', tempStr); 
NotifStrCtempStr2;' 
end; 


4: 
NotifSndC'This is a Sound Test of the Notifica- 
tion Manager using the Bong sound. ', SNDbong); 

5 " 


NotifSndC'This is a Sound Test of the Notifica- 
tion Manager using the Click sound.’, SNDclick); 
6: 
begin 
NotifSndC'This is a Sound Test of the Notifica- 
tion Manager using the Bong sound.’, SNDbong); 
NotifSndC'This is a Sound Test of the Notifica- 
tion Manager using the Click sound.” , SNDclick); 
end; 
1: 
NotifSndC'^, SNDmonkey); 
8: 
NotifSndC'This is a Sound Test of the Notifica- 
tion Manager using the System Error sound.” -1); 


10: 
бедіп 
RemoveNotif Icon; 
NotifIconC'This is a Icon Test of the Notifica- 
tion Manager using the Diamond Icon.’, SICNdiamond); 
end; 
11: 
begin 
RemoveNotif Icon; 
NotifIconC'^, SICNheyyou); 


end; 
( Call NotifIcon after 60 seconds (3600 ticks).) 
12: 


Timer := TickCount + 3600; 
13: 
RemoveNotif Icon; 
otherwise 
end; 
otherwise 
end; 
HiliteMenu(@); 


end; 
( Simple Mac Main Event Loop. Check to see if it is time to 
display HeyYou Icon.) 
(If Resuming under MultiFinder, Remove Icon Cif any2.) 
procedure MainLoop; 
const 
suspendResumeMessage = 1; 
var 
myEvent: EventRecord; 
whichWindow: WindowPtr; 
tempStr: Str255; 
tempLong: LONGINT; 
begin 
repeat 
if Timer О 0 then 
if TickCount > Timer then 


begin 
RemoveNot if Icon; 
Timer := 0; 


GetDateTime(tempLong); 
IUTimeString(tempLong, TRUE, tempStr); 
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Notif IconCCONCATC ‘Hey You! 
tempStr), SICNheyyou); 
end; 


The Time is ', 


if WaitNextEventCeveryEvent, myEvent, 0, nil) then 
case myEvent.what of 
mouseDown: 
case FindWindow(muEvent.where, whichWindow) of 
inSusWindow: 
SustemClick(muEvent, whichWindow); 
inMenuBar : 
DoCommand(MenuSe lect (myEvent . where )); 
otherwise 
end; 
Арр4Еу(: 
if BitShif tCmyEvent .теѕѕаде, -24) = SuspendRe- 
sumeMessage then 
if Odd(muEvent.message) then 
RemoveNotif Icon; 
otherwise 
end; 
until doneF lag; 
end; 


( Deletes Menus and removes Icon Notification Request Cif 
any). 


procedure CloseDown; 

begin 
RemoveNotif Icon; 
DeleteMenu( 181); 
De leteMenuC 102); 
DeleteMenuC 103); 
DisposeMenu(CmuM 1); 
DisposeMenuCmymM2 ); 
DisposeMenu(muM3); 

end; 


( Main Program . ) 
begin 
InitGraf (ëthePort); 
InitFonts; 
FlushEvents(everuEvent, 0); 
InitWindows; 
InitMenus; 
TEInit; 
InitDialogs(nil); 
InitCursor ; 
DoAbout; 
if CheckSystem then 
begin 
SetUp; 
MainLoop; 
CloseDown; 
end; 
end. 


Listing: 
/* 


HeyYou.r 


HeyYou.r - Resources for HeyYou 
Notification Manager Example Program for MacTutor by Steve 
Sheets 
*/ 
#1пс1шде “Турез.г” 
type ‘HEY!’ as ‘STR '; 


resource ‘HEY!’ (0) ( 
“Notification Manager Example for MacTutor by Steve Sheets” 


2 
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resource ‘BNDL’ (128) ( 
(HEY! /, 
0, 
( /* array ТуреАггау: 2 elements */ 
/* (1) */ 
ICN’, 
( /* array IDArray: 1 elements */ 
/* [1] */ 
0, 128 


7 

/* (2) */ 

“ЕЕЕ”, 

( /* array IDArray: 1 elements */ 

/* [1] */ 
| 0, 128 
) 
); 


resource 'FREF^ (128) ( 
APPL’, 
0, 


wn 


); 


resource ‘ICN#’ (128) ( 

( /* array: 2 elements */ 
/* [1] */ 
$“FFFF FFFF 807F FFFF 807F FFFF 807F 
$^807F FFFF 807F COFF 887F 003F 887E 
%”887С 000Ғ 8078 0007 8079 5047 8071 
%”8071 DOC3 8071 5083 8071 5C83 8070 
$?8070 0003 8070 0003 8071 5043 8071 
$"87F1 0543 81Е0 9543 81Ғ0 90С7 81F0 
$?81F0 000Ғ 81Е0 001Е 8Ғ80 007Ғ BIFF 
$?81FF FFFF 81FF FFFF 81FF FFFF FFFF 
/* [2] */ 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF 

| $^ЕЕЕЕ FFFF FFFF FFFF FFFF FFFF FFFF 

); 


resource ‘SICN’ (500, purgeable) ( 
( /* array: 1 elements */ 
/* (1) */ 
$”7FFC 8002 АВАА AA2A ВВЗА AA12 АВ92 
%”АВАА AAAA BAAA 92AA 93BA 8002 ТЕҒС” 
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FFFF” 
00 IF” 
5143" 
0003" 
5543" 
0001" 
FFFF^ 
ЕЕЕЕ”, 


FFFF” 
FFFF” 
FFFF” 
FFFF^ 
FFFF” 
ЕЕҒЕ” 
FFFF” 
FFFF^ 


8002" 


J. 


resource “ICON (500) ( 
$“FFFF FFFF 807F FFFF 807F FFFF 807F ҒҒҒҒ” 
$?807F FFFF 807F COFF 887F ØØ3F 887E 001Ғ” 
%”887С 000Ғ 8078 0007 8079 5047 8071 5143" 
%”8071 D9C3 8071 5083 8071 5C83 8070 0003" 
$"8070 0003 8070 0003 8071 5043 8071 5543" 
$^87F1 0543 81F0 9543 81Ғ0 90С7 81F0 0007" 
%”81Ғ0 000Ғ 81-0 001Ғ 8Ғ80 007Ғ 81FF FFFF” 

$^8IFF FFFF 81FF FFFF BIFF FFFF FFFF FFFF^ 


data ‘SIZE’ (-1) ( 
%%5800 0006 4000 0006 4000" 


д 


resource ‘ALRT’ (500) ( 
(40, 76, 164, 436), 
500, 
( /* arrau: 4 elements */ 
/* (1) */ 
OK, visible, sound], 
/* [2] */ 
OK, visible, soundi, 
/* [3] */ 
OK, visible, sound, 
/* [4] */ 
OK, visible, sound! 
); 


resource ‘DITL’ (500) ( 
( /* array DITLarray: 3 elements */ 

[5 EHA 

(84, 150, 104, 210), 

Button ( 
enabled, 
"Ok? 

), 

/* [2] */ 

(20, 84, 74, 344), 

StaticText ( 
disabled, 
“A Notification Manager example program f” 
“or MacTutor by Steve Sheets Requires Sys” 
“tem 6.0 or higher" 


), 
/* [3] */ 
(10, 10, 74, 74), 
Icon ( 
disabled, 
500 
) 
) 
); 


MIDI Connections 
MIDI User Interface 


MIDI and the User Interface 

This is an article that takes a look at the Macintosh’s Dialog 
Box routines, and how they can be used effectively. The PopUp 
menus and ArrowEditText controls described here are an attempt 
at getting the greatest use out of limited space in a Dialog Box. 
Techniques like this are important in programs that make use of 
MIDI like sequencers and patch librarians, for example. Exten- 
sive use of dialogs can be found in these type of programs. 


The significance of the user interface 

This article is going to take a little bit of a different slant from 
the previous MIDI articles because I think it is important to talk 
about the human interface considerations for a bit. It seems that 
the thing that separates good Macintosh programs from average 
onesis the way that the user interface is implemented. A program 
has to look and feel like a Macintosh program should. The best 
way to accomplish this is to try to follow the Apple guidelines for 
doing things, and only using alternate techniques when abso- 
lutely nothing else will work. Probably the first book that 
aspiring Macintosh programmers should read is Human Inter- 
faced Guidelines published by Addison Wesley. 


Dialogs in MIDI programs 

Most of the things that take place in a MIDI program happen 
in Dialog Boxes. These structures have been made very simple 
to use by Apple, and they can lead the user through a great deal 
of setup information that would otherwise be difficult to deal 
with. Getting the most out of a particular dialog box can be a 
challenge, though. There is limited space and a lot of things to 
be accomplished, so what is the best way to communicate with 
the user while making the most efficient use of space? In 
addressing this problem, I’ve found the pop-up menu idea to be 
very useful. It takes up very little space in a dialog box until it is 
selected. At that point it can display a large range of choices. 
Now, this can also be done with the list manager by displaying a 
scrolling list of choices, but that would take up more room than 
the pop-up menu solution. Another technique that I have made 
use of is what I call an Edit Text Arrow Control. I use this for the 
input of numbers. It can be used like a standard Edit Text Item, 
but, in addition, there is an up/down arrow control associated 
with the item that allows the user to select a number with the 
mouse instead of having to use the keyboard. In order to provide 
an example of these two techniques I have written a sample 
application that lets the user change the MIDI program number 
оп а synthesizer. We'll get to the application in a short time, but 
first we should talk about the Pop-up Menus and the Arrow Edit 
Text Control. 
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MIDI Channel Number: [2 ] 


MIDI Program Number: ао? B 


[x] Modem Port 


ETD 


C] Printer Port 


Figure 1. Example Dialogbox 
The RefCon field 
Fortunately for us, Apple gave us the RefCon field of a 
window record. This is a longint that we can use however we 
want. Iuse this field to give each Dialog a unique number that 
can be used to calculate a number for the User Items in a Dialog. 


Both the Pop-Up Menus and the ArrowEditTextCtl use this 
number to identify themselves. 


PopUp Menus 

These routines are based on some samples distributed by 
Apple, and produce the standard Pop-Up Menus as described in 
the User Interface Guidelines. The way I have implemented them 
is closely related with the items in the dialog box that I created 
with the Resource Editor. This is because the PopUp menu is 
made up of two dialog items, a static text item and a user item. 
My routines expect the UserItem item Number to be one greater 
then the staticText item number. This works out to be a logical 
way tocreate the PopUp menu location from the Resource Editor. 
Just create the StaticText first, then create the Userltem. Іп 
addition to the items in the dialog box you have to define the 
menu as a resource with the Resource Editor. The important 
thing here is that the menu resource number has to be the 
UserItem item number plus the value in the Dialog's RefCon 
field (whew). I set the dialog's RefCon field to 200 in my 
program, and if I were going to use additional dialog's I could 
assign RefCon values of 300, 400, 500, etc. to them. If these 
numbering relationships are kept straight then it is pretty easy to 
create and use PopUp Menus. There are only two routines to use 
for all of the PopUp Menus in your application: 
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procedure DrawPopUp(TheDialog : DialogPtr; theItem : integer); 
function PUMenuAction(theDialog : DialogPtr; PopUpItem : integer) 
: integer; 


The DrawPopUp procedure is called by PUMenuAction and 
also by the Dialog Manager after you install it as your UserItem 
drawing proc. Otherwise, you never actually call this routine 
yourself. PUMenuAction is what you call when there's a 
mousedown in the UserItem that is associated with the particular 
PopUp menu. PUMenuAction returns the menu item number as 
its result. 


The ArrowEditTextCtl 

EditText items in dialog boxes are great! They are pretty 
easy to use, and provide a standard way for the user to enter 
information into the Mac. The only thing aboutthem that bothers 
me sometimes is that they require the user to type in the informa- 
tion, thereby taking the hand off of the mouse. I wanted a way to 
change text in an EditText item that would work from the mouse, 
so I came up with the ArrowEditTextCtl. The ArrowEditTextCtl 
is a regular EditText item with a frame drawn around it. Along 
the right side of the frame are the up and down arrows that 
increment or decrement the number in the EditText item. The 
ArrowEditTextCtl is a structure that also requires two dialog 
items defined for it. There is an EditText box and a UserItem. 
The EditText item number must be one less that the UserItem 
item number. Some care must be taken when creating the 
EditText and Userltem’s. First create your EditText box (which 
must be 16 pixels high), then create the UserlItem to be the same 
coordinates except -3 top, -3 left, +3 bottom, and +13 right. Once 
you do that the control will draw itself properly. There are two 
routines that are used to implement the ArrowEditTextCtl’s in a 
program: 
procedure DrawArrowETCtlCTheDialog : DialogPtr: theItem : 
integer); 


function ArrowCtlActionCTheDialog : DialogPtr; theItem : 
integer; limitLo : integer; limitHi : integer) : integer; 


All you have to do with the Draw ArrowETCtl procedure is 
install it as the UserItem's drawing proc. Then you call Ar- 
rowCtlAction in response to a mousedown in the UserItem. The 
way itis written this routine will return the integer that is selected 
by either using the up and down arrows, or typing it in the 
EditText box. 


Using the MIDI library 

The MIDI library is a set of routines that were described in 
the December issue of MacTutor, so I don’t think we need to 
spend any more time on them here. All the program is doing as 
far as MIDI is concerned is sending a program change message, 
which is pretty trivial, really. [There are some updates to Kirk's 
MIDI library from the last published version. They are not 
printed in thearticle, but they are included on the source code disk 
for this issue. -ed] 


The MIDI Ctis Application 
The application is pretty simple, really. It just gives you a 
menu with one item in it. When you select the menu item a dialog 


@ The Best of MacTutor, Vol. 5 


box appears on the screen. This is the dialog that demonstrates 
the use of the PopUp menu and the ArrowEditTextCtl. The 
dialog box is created as ‘not visible’ by the Resource Editor. This 
lets us do our GetNewDialog call and install all of the drawing 
procedures for the UserItem's as well as set up the RefCon field 
of the dialog. After all of that is done we do a call to ShowWin- 
dow to make the dialog visible. This works out to be much faster 
than watching the dialog draw all of its items on the screen. The 
function MyDialogFilter is used to watch for the mouse clicks in 
our Userltem’s as well as check for keyboard input and making 
sure that a valid number gets typed into the EditText item. The 
rest of the program is your standard vanilla Macintosh applica- 
tion. 


Listing: MIDICtIs 


( Kirk Austin, 4/9/88 ) 
(This shows how to use a dialog box in a MIDI program) 


PROGRAM ShellExample; 


USES 
ROM85, ColorQuickDraw, ColorMenuMgr, LSPMIDI; 


( Global Constants ) 
CONST 
Null = '^ 


AppleMenuID = 1; 
FileMenuID = 
EditMenuID = 
MIDIMenuID = 
PopMenuID = 2 
Dialog’s RefCon) 


2; 
3; 
4; 

06; (Item number plus the value in the 


AboutID = 200; 
MIDIDialog = 201; 
MIDIDialogRefCon = 200; 
(Items in our dialog box) 
OKOutline = 8; 


AEditText = 3; 

ArrowETCt] = 4; 

iPopPrompt = 5; (the Prompt staticText) 
iPopUp = 6; (the Pop-up userltem) 


ModemCheckBox = 9; 
PrinterCheckBox = 10; 


( Global Tupes ) 
TYPE 


MIDIPrgData = RECORD 
MIDIChan : integer; 
MIDIProg : integer; 
ModemActive : boolean; 
PrinterActive : boolean; 

END; 
MPDPtr = “MIDIPrgData; 
MPDHdle = “MPDPtr; 


( Global Variables ) 
VAR 


myMenus : ARRAY[AppleMenuID..MIDIMenuID] OF MenuHandle; 

Done : Boolean; ( true when user selects quit) 

TextCursor : CursHandle; (handle to the text entry cursor) 

ClockCursor : CursHandle; (handle to the waiting watch 
cursor) 

PopMenuHdle : MenuHandle; 

TheMPDPtr : MPDPtr; 

TheMPDHdle : MPDHdle; 

TheResHdle : handle; 

TheResRefNum : integer; 
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TheType : integer; 
TheHandle : Handle; 
TheRect : Rect; 


PROCEDURE ShowAbout ; 
VAR 


theDlog : DialogPtr; 
oldPort : GrafPtr; 
BEGIN 
GetPortColdPort); А 
theDlog := GetNewDialogCAboutID, NIL, Pointer(-1)); 
SetPortCtheD10g); 
DrawDialogCtheD10g); 
WHILE NOT Button DO 
SystemTask ; 
DisposDialog( theDlog); 
SetPortColdPort); 
END; 


PROCEDURE LaunchIt (mode : integer; 
VAR fName : Str255); 
(The compiler has just pushed a word for the mode, and a 
pointer to the string) 
INLINE 
$204F, (novea.1 a7,80;(a0) is ptr to string, 4(ай) is mode) 
$A9F2; (Launch) 


PROCEDURE DoXfer; 
VAR 
where : Point; 
reply : SFReply; 
vRef : integer; 


thefName : Str255; 
textType : SFTypeList; 
BEGIN 
where.h :- 80; 


where.v := 55; 
textTupe[0] := ‘APPL’; 
SFGetFileCwhere, Null, NIL, 1, textType, NIL, reply); 
WITH reply DO 
IF NOT good THEN 
thefName := Null 


thefName := fName; 
vRef := vRefNum 
END; 
IF thefName <> Null THEN 
BEGIN 
Done := true; 
IF SetVol(NIL, vRef) = noErr THEN 
LeunchItCO, thefName) 
END 
END; 


PROCEDURE Draw0KOutline CtheDialog : DialogPtr; 
theItem : INTEGER); 
VAR 
savePen : PenState; 


GetPenState(savePen); (save the old pen state) 
GetDItemCTheDialog, TheItem, ТһеТуре, TheHandle, TheRect); 

(get the item’s rect) 
PenSize(3, 3); (make the pen fatter) 
InsetRect(TheRect, -4, -4); 
FrameRoundRect(TheRect, 16, 16); (draw the ring) 
SetPenState(savePen); (restore the pen state) 

END; (DrewOKOutline) 


(DrawPopUp procedure was made to be as general as possible) 
(The main thing to remember is that it expects PopUpMenuID to) 
(be TheItem + TheRefCon of the Dialog.Also,Prompt item number) 
(must be 1 less than the Pop Up Menu item number) 

PROCEDURE DrawPopUp (TheDialog : DialogPtr; 
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Theltem : integer); 
CONST 
(constants for positioning the default item within its box) 


leftSlop = 13; (leave this much space on left of title) 


rightSlop s 5; ( this much on right) 

botSlop = 5; ( this much below baseline) 
VAR 

TheType : integer; 

TheHandle : handle; 

r : Rect; 


TheString : Str255; 

newWid, newLen, wid : INTEGER; 
TheMenuHdle : MenuHandle; 
TheMenuItem : integer; 

i : integer; 

TheChar : char; 


TheRefCon : integer; 
MenuItemsCount : integer; 
BEGIN 


(Get the menu that is associated with this Dialog Item 


(TheItem + TheRefCon)) 


TheRefCon := LoWord(GetwWRefConCWindowPtr(TheDialog))); 
TheMenuHdle := MenuHandle(GetResource( ‘MENU’, TheItem + 


TheRefCon)); 


(Now, figure out which menu item is the current selection by 


scanning for a check mark) 


MenuItemsCount := CountMItemsCTheMenuHdle); 
TheMenuItem := 0; 
і := 1; 
ВЕРЕАТ 
GetItemMarkCTheMenuHdle, i, TheChar); 
IF TheChar = char(CheckMark) THEN 
TheMenultem := i; 
Lett) 
UNTIL CTheMenuItem <> Ø) OR Ci = MenuItemsCount + 1); 
IF TheMenuItem = @ THEN 
BEGIN 
SetItemMarkCTheMenuHdle, 1, CHRCcheckMark)); 


(check the first item) 


TheMenuItem := 1; 


ND; 
GetItem(TheMenuHdle, TheMenuItem, TheString); 


(get currently-selected item) 


GetDItemCTheDialog, TheItem, ТһеТуре, TheHandle, г); 


(set up the rectangle) 


WITH r DO 
BEGIN 
InsetRect(r, -1, -1); (make it a little bigger) 
(Make sure title fits. Truncate it add an ellipses (”.”)) 
(if it doesn’t (bu the way, "." is option-semicolon)) 
wid := (right - left) - CleftSlop + rightSlop); 


(available string area) 


newWid := StringWidthCTheString); (get current width) 
IF newWid > wid THEN 
BEGIN (doesn’t fit - truncate it) 
newLen := LENGTH(TheString); 
(current length in characters) 
wid := wid - CharWidth(’..’); 
(subtract width of ellipses) 


REPEAT (until fits Cor we run out of characters?) 
(drop the last character and its width) 
newWid := newWid- CharWidth(TheStringI[newLen1); 
newLen := PREDCnewLen); 
UNTIL CnewWid <= wid) OR CLENGTH(TheString) = 0); 
(add the ellipses character) 
newLen := SUCC(newLen); (one more char) 
TheStringInewLen] := '.^; (it’s the ellipses) 
TheString(0] := CHRCnewLen); (fix the length) 
END; 


(drew the box and its drop shadow) 


FrameRect(r); 
Movelo(right, top + 2); 
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LineTo(right, bottom); 
LineToCleft + 2, bottom); 
(draw the string) 
MoveToCleft + LeftSlop, bottom - BotSlop); 
DrawStr ingCTheStr ing); 
END; 
END; (DrawPopUp) 


FUNCTION PUMenuAction CTheDialog : DialogPtr; 


PopUpItem : integer) : integer; 
VAR 
popLoc : Point; 
newChoice : INTEGER; 


chosen, ignoreLong : LongInt; 
TheString : Str255; 


Theltem : integer; 
TheType : integer; 
TheHandle : handle; 


PromptRect : rect; 
PopUpRect : rect; 
TheMenuHdle : MenuHandle; 
TheRefCon : integer; 
TheMenuID : integer; 
TheMenuItem : integer; 
i : integer; 
TheChar : char; 
MenultemsCount : integer; 
BEGIN 
PUMenuAction := 0; 
(Get the menu that is associated with this Dialog Item 
(PopUpItem + TheRefCon)) 
TheRefCon := LoWord(GetwWRefCon(WindowPtr(TheDialog))): 
TheMenuID := PopUpItem + TheRefCon; 
TheMenuHdle := MenuHandle(GetResource( ‘MENU’, PopUpItem + 
TheRefCon)); 
(Now, figure out which menu item is the current selection by 
scanning for a check mark} 
MenuItemsCount := CountMI tems( TheMenuHdle); 
TheMenuItem := Ø; 
і := 1; 
REPEAT 
GetI temMark(TheMenuHdle, i, TheChar); 
IF TheChar = char(CheckMark) THEN 
TheMenuItem := i; 
pus pv 1 
UNTIL CTheMenuItem <> 2) OR Ci = MenuItemsCount + 1); 
(Call PopUpMenuSelect and let user drag around. Note that ) 
(Сбор, left) parameters to PopUpMenuSelect are our item’s, ) 
(converted to global coordinates.) 
GetDItemCTheDialog, PopUpItem - 1, TheType, TheHandle, 
PromptRect); 
GetDItemCTheDialog, PopUpItem, TheType, TheHandle, 
PopUpRect); 
InvertRect(PromptRect); (hilight the prompt) 
InsertMenuCTheMenuHdle, -1); (insert our menu in menu list) 
PopLoc := PopUpRect.TopLeft; (copy our item’s topleft) 
LocalToGlobal(PopLoc); (convert back to global coords} 
CalcMenuSizeCTheMenuHdle); (Work around Menu Mgr bug) 
WITH popLoc DO 
chosen := PopUpMenuSelectCTheMenuHdle, v, h, TheMenu- 
Item); 
InvertRect(PromptRect); (unhilight the prompt) 
DeleteMenu(TheMenuID); (remove our menu from menu list) 
(Was something chosen?) 
IF chosen © 0 THEN 
BEGIN (yep, something was chosen) 
newChoice := LoWord(chosen); (get chosen item number) 
IF newChoice <> TheMenuItem THEN 
BEGIN 
(the user chose an item other than the current one) 
SetItemMarkCTheMenuHdle, TheMenuItem, ' ^); 
(unmark the old choice) 
SetItemMarkCTheMenuHdle, newChoice, 
CHR(checkMark)); (mark the new choice) 
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PUMenuAction := newChoice; 
(Draw the new title) 
EraseRect(PopUpRect); 
DrawPopUp(theDialog, iPopUp); 
END; (if this choice was not the current choice) 
END; (if something was chosen) 
END; (of PUMenuAction) 


(EditText number must be 1 less than ArrowUserItem number) 
PROCEDURE DrawArrowETCt] CTheDialog : DialogPtr; 
TheItem : integer); 
VAR 

theType : Integer; 
theHandle : Handle; 
theRect : Rect; 
Height : Integer; 
HalfHeight : integer; 
ArrowRect : rect; 


( the type of dlog item ) 
( Handle to the item ) 
( rect which encloses the item) 


BEGIN 

GetDItem(TheDialog, TheItem, theType, theHandle, theRect); 
(get handle to control) 

FrameRect(TheRect); 

InsetRect(TheRect, 2, 2); 

TheRect.right := TheRect.right - 10; 

FrameRect(TheRect); 

GetDItem(TheDialog, TheItem, theType, theHandle, theRect); 
(get handle to control) 

Height := TheRect.bottom - TheRect.top; 

HalfHeight := Height DIV 2; 


HalfHeight := TheRect.bottom - HalfHeight; 
TheRect.left := TheRect.right - 11; 
EraseRect(TheRect); 

FrameRect(TheRect); 


MoveTo(TheRect. left, HalfHeight); (draw bold center line) 
LineToCTheRect.right - 1, HalfHeight); 
MoveTo(TheRect. left, HalfHeight - 1); 
LineTo(TheRect.right - 1, HalfHeight - 1); 


ArrowRect.top := TheRect.top + 4; 
ArrowRect bottom := HalfHeight - 2; 
ArrowRect. left := TheRect.left + 3; 
ArrowRect.right := TheRect.right - 3; 
FillRectCArrowRect, black); 
MoveToCArrowRect.left - 1, ArrowRect.top + 1); 
LineToCArrowRect.right, ArrowRect.top + 1); 
MoveToCArrowRect.left + 1, ArrowRect.top - 1); 
LineToCArrowRect.right - 2, ArrowRect.top - 1); 
MoveToCArrowRect.left * 2, ArrowRect.top - 22; 
LineToCArrowRect.left + 2, ArrowRect.top - 2); 


(draw up arrow) 


ArrowRect.top := HalfHeight + 2; 
ArrowRect.bottom := TheRect.bottom - 4; 
ArrowRect.left := TheRect.left + 3; 
ArrowRect.right := TheRect.right - 3; 
FillRectCArrowRect, black); 
MoveToCArrowRect. left - 1, ArrowRect.bottom - 2); 
LineToCArrowRect. right, ArrowRect.bottom - 2); 
MoveToCArrowRect. left + 1, ArrowRect.bottom); 
LineToCArrowRect.right - 2, ArrowRect.bottom); 
MoveToCArrowRect.left + 2, ArrowRect.bottom + 1); 
LineToCArrowRect. left + 2, ArrowRect.bottom + 1); 
END; 


FUNCTION ArrowCtlAction (TheDialog : DialogPtr; 
TheItem : integer; 
LimitLo : integer; 
LimitHi : integer) : integer; 
VAR 
theType : Integer; 


theHandle : Handle; 
theRect : Rect; 
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TheNum : longint; 
TheString : Str255; 
Height : Integer; 
HalfHeight : integer, 
ArrowRect : rect; 
ThePoint : point; 
Inverted : boolean; 
HowLong : longint; 
TickResult : longint; 
UpArrowRect : rect; 
DnArrowRect : rect; 
TheTEHandle : handle; 
GoingUp : boolean; 


PROCEDURE BtnDelay Cticks : integer); 
VAR 
dummy : longint; 
i: integer; 
BEGIN 
i := ticks; 
IF ticks = 0 THEN 
i := 1; 
REPEAT 
Delau(1, dummy); 
i := 1-1; 
UNTIL Ci = 0) OR NOT button; 
END; 


BEGIN 
GetDItemCTheDialog, TheItem - 1, theTupe, theHandle, 
theRect); (get handle to control) 
TheTEHandle := TheHandle; 
GetITextCTheTEHandle, TheString); 
StringToNumCTheString, TheNum); 
ArrowCtlAction := loword(TheNum); 


GetDItemCTheDialog, TheItem, theType, theHandle, theRect); 


(get handle to contro!) 
Height := TheRect.bottom - TheRect. top; 
HalfHeight := Height DIV 2; 
HalfHeight := TheRect.bottom - HalfHeight; 
TheRect.left := TheRect.right - 11; 
UpArrowRect := TheRect; 
UpArrowRect.bottom := HalfHeight; 
DnArrowRect := TheRect; 
DnArrowRect.top := HalfHeight; 
Inverted := false; 
HowLong := 22; 
GetMouseCThePoint 2; 
IF (PtInRect(ThePoint, TheRect2)) AND Stilldown THEN (we 
need to hilite an arrow) 
BEGIN 
IF PtInRectCThePoint, UpArrowRect) THEN 
BEGIN 
ArrowRect := UpArrowRect; 
GoingUp := true; 
END 
ELSE 
BEGIN 
ArrowRect := DnArrowRect; 
GoingUp := false; 
END; 
REPEAT 
GetMouseCThePoint); 
IF NOT PtInRect(ThePoint, ArrowRect) THEN 
BEGIN 
IF inverted THEN 
BEGIN 
TheRect := ArrowRect; 
InsetRect(TheRect, 1, 1); 
Inver tRect(TheRect); 
Inverted := false; 
END; 
END 
ELSE 
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BEGIN 
IF NOT Inverted THEN 

BEGIN 
TheRect := ArrowRect; 
InsetRect(TheRect, 1, 1); 
InvertRect(TheRect); 
Inverted := true; 

END; 


GetITextCTheTEHandle, TheString); 
StringToNum(TheString, TheNum); 
IF GoingUp THEN 
BEGIN 
IF TheNum O LimitHi THEN 
BEGIN 
TheNum := TheNum + 1; 
IF TheNum > LimitHi THEN 
TheNum := LimitHi; 
ArrowCtlAction := loword(TheNum); 
NumToString(TheNum, TheString); 
SetITextCTheTEHandle, TheString); 
SellText(TheDialog, TheItem - 1, 0, 
32767); 
END; 
END 
ELSE 
BEGIN 
IF TheNum € LimitLo THEN 
BEGIN 
TheNum := TheNum - 1; 
IF TheNum < LimitLo THEN 
TheNum := LimitLo; 
ArrowCtlAction := lowordCTheNum); 
NumToStringCTheNum, TheString); 
SetITextCTheTEHandle, TheString); 
SellText(TheDialog, TheItem - 1, Ø, 
32161); 
END; 
END; 
BtnDelayCHowLong); 
IF HowLong > 3 THEN 
HowLong := HowLong - 2; 
END; 
UNTIL NOT StillDown; 
DrawArrowETCt1(TheDialog, TheItem); 
END; 
END; (ArrowCtlAction) 


FUNCTION MyDialogFilter CtheDialog : DialogPtr; 
VAR theEvent : EventRecord; 
VAR item : integer) : Boolean; 
(function called bu ModalDialog for everu event that occurs) 
( while in control. It is used to “filter” events so you) 
( can do things when certain events occur. It is used to } 
( change cursor to an I beam when editing text. The routine } 
( also handles keyboard entry; limiting text input to numbers) 
( and making return & enter the same as clicking OK button } 


CONST 
CrCode = 13; {ASCII code for RETURN) 
EnterCode = 3; (ASCII ccode for ENTER) 
BsCode = 8; (ASCII code for Back Space) 
TabCode = 9; (ASCII ccode for Tab) 

VAR 
mouseLocation : point; (holds coordinates of mouse loc.) 
TheHandle : Handle; (used for dummy purpose here) 
TheType : Integer; (used for dummy purpose here) 
TheRect : Rect; (used for dummy purpose here) 
TextBox! : Rect; (defines area to test for cursor change) 
TheString : Str255; 
TheNum : longint; 
TheDlogRecPtr : DialogPeek; 
Тһе (еп : integer; 
TheChoice : integer; 
TheMenuItem : integer; 
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i : integer; 
TheChar : char; 


TheMenuHdle : menuHandle; 
ignorelong : longint; 
BEGIN 


MyDialogFilter := false; (let modalDialog handle event) 
GetDItemCtheDialog, AEditText, TheType, TheHandle, 
TextBox1); (chg cur in area) 


CASE theEvent.what OF 
nullEvent : (nothing happening chk if cursor to change) 
BEGIN 
GetMouse(CmouseLocat ion); 
IF PtinRect(mouseLocation, TextBox1) THEN 
SetCursor(TextCursor**) 
ELSE 
SetCursor (arrow); 
GetITextCTheHandle, TheString); 
typed in an invalid number} 
StringToNumCTheString, TheNum); 
IF TheNum > 128 THEN 
BEGIN 
SysBeep( 10); 
TheNum := 128; 
NumToStringCTheNum, TheString); 
SetITextCTheHandle, TheString); 
SellText(TheDialog, AEditText, 0, 32767); 
(hilite the editable text) 
END; 
IF TheNum « 1 THEN 
BEGIN 
SysBeep( 10); 
TheNum := 1; 
NumToString(TheNum, TheString); 
SetIText(TheHandle, TheString); 
SellText(TheDialog, AEditText, 0, 32767); 
(hilite the editable text) 


(see if someone 


2 


END; 


mouseDown : 
BEGIN (*Click!”} 
mouselocatior := theEvent.where; 
(copy the mouse position) 
GlobalToLocal(mouselocation); (convert to local 
coordinates) 


(Was the click in a user item?) 
IF KFindDItemCtheDialog, mouseLocation) + 1) = 4 
THEN 
BEGIN 
TheMPDPtr*^.MIDIProg := 
ArrowCtlActionCTheDialog, 4, 1, 128); 
END; (if clicked in ArrowEditTextCtl userItem) 


IF KFindDItemCtheDialog, mouseLocation) + 1) = 
iPopUp THEN 
BEGIN (Clicked in the pop-up box) 
TheChoice := PUMenuAction(TheDialog, iPopUp); 
IF TheChoice € 0 THEN 
BEGIN 
MyDialogFilter := TRUE; (dialog is over) 
TheMPDPtr^.MIDIChan := TheChoice; 
item := iPopUp; (have ModalDialog return 
that the user changed items) 
END; 
END; (if clicked in our userItem) 
END; (mousedown case) 
kegDown, autokey : (to follow std. procedure, chk if 
RETURN or ENTER was pressed) 
BEGIN 
IF CtheEvent.message MOD 256) IN [crCode, enter- 
Code] THEN 


© The Best of MacTutor, Vol. 5 


BEGIN 
GetDItemCtheDialog, 1, TheType, TheHandle, 
TheRect); 
HiLiteControl(ControlHandle(TheHandle), 1); 
(hilite the OK button) 
Delay(3, ignoreLong); 
HiliteControl(ControlHandle(TheHandle), 0); 
MyDialogFilter := true; 
Item := 1; 
END 
ELSE IF CtheEvent.message MOD 256) IN [bsCode, 
tabCode] THEN 
BEGIN 
END 
ELSE IF (Char(theEvent.message MOD 256) >= 707) AND 
(Char(theEvent.message MOD 256) <= '9^) THEN 
BEGIN 
TheDlogRecPtr := DialogPeek( theDialog); 
TheItem := TheDlogRecPtr^.editField + 1; 
( find out which EditText Item we are in ) 
GetDItemCtheDialog, Theltem, TheType, 
TheHandle, TheRect); 
GetIText(TheHandle, TheString); 
IF (Length(TheString) > 2) THEN 
SetITextCTheHandle, Null); 
( set it to Null if there are more than 3 characters ) 
END 
ELSE 
MyDialogFilter := true; 


OTHERWISE 


END; (of the CASE statment) 
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PROCEDURE SendMIDI; 
VAR 
dummy : longint; 
BEGIN 
IF TheMPDPtr^.ModemActive THEN 
BEGIN 
InitSCCA; 
TXMIDIACTheMPDPtr^.MIDIChan + 191); 
TXMIDIACTheMPDPtr^.MIDIProg - 1); 
DelayC1, dummy); 
ResetSCCA; 
END; 
IF TheMPDPtr^.PrinterActive THEN 
BEGIN 
Ini tSCCB; 
TXMIDIBCTheMPDPtr^.MIDIChan + 191); 
TXMIDIBCTheMPDPtr^.MIDIProg - 1); 
Delay( 1, dummy); 
ResetSCCB; 
END; 
END; (of SendMIDI) 


PROCEDURE ProcessMenu (codeWord : Longint);( menu selec) 


VAR 
menuNum : Integer; 
itemNum : Integer; 
NameHolder : str255; 


dummy : Integer; 
yuck : boolean; 
oldPort : GrafPtr; 
aDialog : DialogPtr; 
ItemHit : integer; 
TheItemHandle : handle; 
TheItemType : integer; (type of the selected item) 
TheItemRect : rect; {bounding box of the selected item) 
TheNum : longint; 
TheString : Str255; 
BEGIN 
IF codeWord €» 0 THEN ( nothing was selected) 
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BEGIN 
menuNum := HiWord(codeWord); 
itemNum := LoWord(codeWord); 
CASE menuNum OF ( the different menus) 
AppleMenuID : 
BEGIN 
IF itemNum < 3 THEN 
BEGIN 
ShowAbout ; 
END 
ELSE 
BEGIN 
GetItem(nyMenus [AppleMenuID], itemNum, 
МатеНо1дег ); 
dummy 
END; 
END; 
FileMenuID : 
BEGIN 
CASE ItemNum OF 
1 


:= OpenDeskAccCNameHolder 2; 


BEGIN 
DoXfer ; 
END; 

2: 


END; 
END; 
EditMenuID : 
BEGIN 
yuck := SystemEditCitemNum - 1); 
END; 
MIDIMenuID : 
BEGIN 
GetPortColdPort); 
(Get a menu) 
PopMenuHd]e 
menu Cits title is ignored)) 
SetItemMarkCPopMenuHdle, TheMPDPtr .MIDIChan, 
CHR(checkMark)); (check it} 
aDialog := GetNewDialog(MIDIDialog, NIL, 
WindowPtr(- 122; 
SetPortCaDialog); 
SetWRef ConCWindowPtrCaDialog?, MIDIDialo- 
gRefCon); (set the defaults) 
GetDItemCaDialog, AEditText, theType, 
TheHandle, TheRect); 
TheNum := TheMPDPtr^ .MIDIProg; 
NumToString(TheNum, TheString); 
SetITextCTheHandle, TheString); 
GetDItemCaDialog, ModemCheckBox, theType, 
TheHandle, TheRect); 
IF TheMPDPtr^.ModemActive THEN 
SetCtlValueCControlHandleCTheHandle2, 1); 
GetDItemCaDialog, PrinterCheckBox, theType, 
TheHandle, TheRect); 
IF TheMPDPtr^.PrinterActive THEN 
SetCtlValueCControlHandleCTheHandle2, 1); 
(Find out where our UserItems are, set their item handles to ) 
(a pointer to the drawing procedures) 
GetDItemCaDialog, ArrowETCt], theType, 
TheHandle, TheRect?; 
SetDItemCaDialog, ArrowETCt], theType, @DrawAr- 
rowETCt], TheRect); 
GetDItemCaDialog, iPopUp, theType, TheHandle, 


‚= GetMenuCPopMenuID); (Create а 


TheRect); 

SetDItemCaDialog, iPopUp, theType, @DrawPopUp, 
TheRect); 

GetDItemCaDialog, OKOutline, theType, 
TheHandle, TheRect); 

SetDItemCaDialog, OKOutline, theType, @Draw0K- 
Outline, TheRect); 
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) SellText(aDialog, 3, Ø, 32767);(hilite editable 
text 
ShowWindow(WindowPtr(aDialog)); (show window) 
REPEAT 
ModalDialog(@MyDialogFilter, ItemHit); 
(will process all events while dialog is up) 
CASE itemHit OF 


1: 
BEGIN (this is the Send Button item) 
SendMIDI; 
END; 


BEGIN (this is the Done Button item) 
DisposDialog(aDialog); 
SetPort(oldPort); 

END; 


iPopUp : 
BEGIN (this is the PopUpMenu item} 
SysBeep( 1); 
END; 


ModemCheckBox : 
BEGIN (this is the Modem Check Box item} 
GetDItemCaDialog, ModemCheckBox, 
theType, TheHandle, TheRect); 
IF TheMPDPtr^.ModemActive THEN 
BEGIN 
TheMPDPtr^.ModemActive := false; 


SetCtlValueCControlHandleCTheHandle2, 0); 
END 
ELSE 
BEGIN 
TheMPDPtr*.ModemActive := true; 


SetCt1ValueCControlHandle(TheHandle), 1); 
END; 
END; 


PrinterCheckBox : 
BEGIN (this is Printer Check Box item} 
GetDItemCaDialog, PrinterCheckBox, 
theType, TheHandle, TheRect); 
IF TheMPDPtr^.PrinterActive THEN 
BEGIN 
TheMPDPtr* .PrinterActive:= false; 


SetCtlValueCControlHandleCTheHandle), 0); 

END 

ELSE 
BEGIN 
TheMPDPtr^.PrinterActive := true; 

SetCtlValueCControlHandleCTheHandle), 1); 

END; 

END; 
OTHERWISE 


2 
END; (case of item hit) 
UNTIL ItemHit = 2; (We’re done with Dialog) 
END; 
END; 
HiliteMenu(0); 
END; 
END; 


PROCEDURE DealWithMouseDowns (theEvent : EventRecord); 
VAR 
location : Integer; 
windowPointedTo : WindowPtr; 
mouseloc : point; 
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windowLoc : integer; 
VandH : Longint; 
Height : Integer; 
Width : Integer; 
BEGIN 
mouseLoc := theEvent.where; 


windowLoc := FindWindow(mouseLoc, windowPointedTo); 


CASE windowLoc OF 
inMenuBar : 
BEGIN 
ProcessMenu(MenuSelect(mouseLoc)); 
END; 
inSusWindow : 
BEGIN 
SustemClick(theEvent, windowPointedTo); 
7 
inContent : 
BEGIN 
IF windowPointedTo © FrontWindow THEN 
BEGIN 
SelectWindow(windowPointedTo); 
END; 
END; 
OTHERWISE 
BEGIN 
END; 
END; 
END; 


PROCEDURE DealWithKeyDowns CtheEvent : EventRecord); 
TYPE 
Trick = PACKED RECORD 
CASE boolean OF 
true : ( 
long : Longint 


false : С 
chr3, chr2, chr1, chr® : char 
) 
END; 
VAR 
CharCode : char; 
TrickVar : Trick; 
BEGIN 
TrickVar.long := theEvent .message; 
CharCode := TrickVar chr; 


IF BitAndCtheEvent.modifiers, CmdKey) = CmdKey THEN (check 


for а menu selection) 
BEGIN 
ProcessMenu(MenuKey(CharCode)); 
END 
END; 


PROCEDURE DealWithActivates CtheEvent : EventRecord); 
VAR 
TargetWindow : WindowPtr; 
BEGIN 
TergetWindow := WindowPtrCtheEvent . message); 
IF OddCtheEvent . modif iers) THEN 
BEGIN 
SetPortCTargetWindow); 
END 
ELSE 
BEGIN 


END; 
END; 


PROCEDURE DealWithUpdates CtheEvent : EventRecord); 
VAR 
UpDateWindow : WindowPtr; 
tempPort : WindowPtr; 
BEGIN 
UpDateWindow := WindowPtrCtheEvent . message); 
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GetPortCtempPort); 
SetPortCUpDateWindow); 
BeginUpDateCUpDateWindow); 


EndUpDateCUpDateW indow); 
SetPortCtempPort); 
END; 


PROCEDURE MainEventLoop; 
VAR 
Event : EventRecord; 
ProcessIt : boolean; 
x : byte; 
BEGIN 
REPEAT 
SystemTask; 


ProcessIt := GetNextEvent(everyEvent, Event); ( get the 


next event in queue) 
IF ProcessIt THEN 
BEGIN 
CASE Event.what OF 

mouseDown : 
DealWithMouseDowns(Event); 

AutoKey : 
DealWi thKeyDowns(Event); 

KeyDown : 
DealWithKeyDowns(Event); 

ActivateEvt : 
DealWithActivatesCEvent); 

UpdateEvt : 
DealWithUpdates(Event); 

OTHERWISE 


END; 
UNTIL Done; 
END; 


PROCEDURE MakeMenus; ( get the menus & display them) 


VAR 
index : Integer; 
BEGIN 
FOR index := AppleMenuID TO MIDIMenuID DO 
BEGIN 
nyMenus[indexl := GetMenu( index); 
InsertMenuCmyMenus[ index], 0); 
END; 
AddResMenu(myMenus ГАррТеМепи101, ‘DRVR’); 
DrawMenuBar ; 
END; 


( Program Starts Here ) 

BEGIN 
Done :* false; 
FlushEventsCeveryEvent, 0); 

( initialize routines go here ) 

(get the cursors we use and lock them down - no 
ClockCursor := GetCursor(watchCursor); 
TextCursor :- GetCursor(iBeamCursor ); 
HLockCHandleCClockCursor 22; 
HLock(Handle(TextCursor 22; 

MakeMenus ; 
TheResHdle := GetResource( ‘MIDI’, 128); 
HLock(TheResHdle); 
TheMPDHdle := MPDHdleCTheResHdle); 
TheMPDPtr := TheMPDHdle^; 
InitCursor; 
MainEventLoop; 
ChangedResource(TheResHdle); 
TheResRefNum := HomeResFile(TheResHdle); 
UpdateResF i leCTheResRef Num); 
ReleaseResource(TheResHdle); 

END. 


clutter) 


Pascal Procedures 
Modeless Search and Replace 


Introduction 

While working on development of a utility to speed integra- 
tion of toolbox calls in MacFortran source code, I found myself 
looking for a search and replace routine. Perusal of Macintosh 
Revealed (Vol. 2) quickly led to the toolbox routine Munger 
(rhymes with plunger). A search of back issues of MacTutor also 
revealed the lack of a general discussion of Munger and doing 
find/replace (not even the generic multi-window text editor from 
the January 1987 issue). Thus, I decided to write a general 
purpose find/replace unit from a modeless dialog environment. 


Basic Program Design 

The find/replace unit and the accompanying example pro- 
gram are written in LS Pascal. Conversion to TML, Turbo, or 
MPW shouldbe relatively straightforward. The find/replace unit 
is designed as a standalone unit that requires very little modifica- 
tion to the user’s program to add its capabilities. The modifica- 
tions required include changing the main event loop to handle 
modeless dialog events, adding a new menu, and inserting calls 
to the find/replace unit in your program. When calling the find/ 
replace routines the user passes the current event and a handle for 
the editText to be searched. The program contains a simple text 
edit window, a modeless Find dialog, and a modeless Replace 
Dialog. The program supports desk accessories; cut, copy, and 
paste within the program (but not with desk accessories); and 
should be screen and machine size independent. The program 
requires a 512Ke or later machine. If run on an old 512k machine, 
the program alerts the user and exits back to the Finder. 


Simple Text Editor 
The demonstration program uses the ROM85 library en- 
hancements for the textedit window which allowed me to write 
a barebones editor sufficient for demonstration purposes. The 
text window can be resized, zoomed, and automatically scrolled. 
However, there are no scroll bars, thus movement to text outside 
the visible region must done with the arrow keys. Cut, copy, 
paste, and clear work properly. The text window contents cannot 
be loaded from disk, nor saved to disk. Upon startup (Figure 1), 
the text window contains Lincoln’s Gettysburg Address re- 
trieved from the resource fork. 
Find/Replace Unit 
The Find dialog allows the user to enter text characters and 
does an exact find. The search process can be initiated by 
clicking the ‘Find’ button or pressing the return key. The find 
routine works from the current selection point and does not wrap 
past the end of the textedit record. If found, the current selection 
is set to the string found and highlighted. If not found, the 
machine beeps. The find routine does not support wildcards nor 
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FIGURE 1 


non-printing characters (e.g., control characters). 

The Search dialog allows the user to enter both the search 
and replace strings. Initially, the ‘Search’ button is highlighted 
as the default button. Once the search string has been found (and 
selected, the search routine is just the find routine), the ‘Replace’ 
button is highlighted. If the ‘Replace’ button is selected then the 
occurrence of the search string previously found is replaced. The 
replace string can be null but the find string must contain at least 
one character. When the replace operation is successfully 
completed, the ‘Search’ button returns to the default button. 
Although I have not included a ‘replace all’ button (which could 
easily be integrated), the user can continually press the return key 
searching and replacing. Dialog cut, copy, and paste from the 
text edit scrap is supported within both the Find and Replace 
dialogs. 


Handling Modeless Dialogs 
To properly handle the modeless find and replace dialogs 
four major aspects of modeless dialog event handling must be 
observed carefully: main event loop changes, window events, 
dialog events, and command keys. Each element is relatively 
straightforward, but the combination of the four can lead to some 
confusion and unnecessary coding. 


Main Event Loop 

When a program contains modeless dialogs, the toolbox 
routine IsDialogEvent should be called after calling 
GetNextEvent. Inside Mac (page 1-416) warns that the program 
should call IsDialogEvent even if GetNextEvent returns false. 
When IsDialogEvent returns true the program should drop into 
its routine to handle events for the modeless dialog. Thus, the 
program should call GetNextEvent, then IsDialogEvent, and 
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then start processing on the basis of the booleans returned by the 


two routines. If the program does a 
if GetNextEvent(muEvent) then 
begin 
1f IsDialogEvent(MuEvent) then 
begin 
бо. Моде1е55(М,Еуеп%); 


- structure then null dialog events will not be passed to its 
modeless dialog routines. The alternative used by the program 


in the listing does the following: 
EventF1ag:=GetNextEvent(MuEvent); 
if IsDialogEvent(MyEvent then 
Do_Mode less(MyEvent) 
else if EventFlag then 
begin 


According to Inside Mac, IsDialogEvent returns true for: 
° activate or update events for a dialog window 
° mouse-down events in the content region of an active 
dialog window 
* any other event when a dialog window is active. 
However, the last statement is misleading. 


Window Events 

The structure region of a window is composed of two parts: 
the content region and the window frame (see Inside Mac, pages 
I-271,272). In the standard document window, the window 
frame contains the drag, go-away, and zoom regions (if zoom 
was desired). These regions do not overlap with the content 
region in the standard document window, although they could in 
acustom window definition. Thus, if your modeless dialog uses 
a standard document window (or a noGrowDocument proc) then 
you must be careful in handling events. A mouse-down event in 
the window frame of a modeless dialog will return false for 
IsDialogEvent. The main event loop must handle mouse-downs 
in the drag, go-away, and zoom boxes of a modeless dialog when 
using standard window types. This does not pose a particular 
problem since handling multiple windows for growing, drag- 
ging, and zooming is a standard Mac programming task. 


Dialog Handler 

When IsDialogEvent returns true, the user should pass 
control to a routine that handles the modeless dialog event. This 
routine should call the function | 


DialogSelect( theEvent, whichDialo ,ItemHit):boolean. . 
DialogSelect will return a result of true with the dialog 


pointer in whichDialog and the item number in ItemHit when 
there is 

° amouse-down, key-down, or auto-key event in an enabled 
editText item. DialogSelect will take appropriate action within 
the editText item. 

° a mouse-down event, then mouse released within an 
enabled control item. DialogSelect will call TrackControl while 
the mouse button is down. | 

* amouse-down event in any other enabled item. 

DialogSelect returns а result of false with the dialog pointer, 
whichDialog, undefined and ItemHit undefined when there is 

° an activate or update event for the dialog window. Dia- 
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logSelect will handle the redrawing of all items in the window 
(but will not handle redrawing of the default button). 

° amouse-down, key-down, or auto-key event in a disabled 
editText item. 

° a key-down or auto-key event when no editText item 
exists. 

° a mouse-down event in a control when the mouse is 
released outside the control. 

° а mouse-down event in any other disabled item. 

Thus, your modeless routine calls DialogSelect, letting the 
Dialog Manager handle actions while the user mouses around in 
the dialog. If the user indicates some action within an enabled 
dialog item, then the modeless routine takes appropriate action. 
If DialogSelect returns false then the modeless routine should do 
nothing. Two exceptions to handling returns of false from 
DialogSelect exist. First, if the modeless routine needs to take 
special actions for modeless update or activate events (e.g., 
redrawing the default button, showing selected text) then the 
routine must check for these types of events after DialogSelect 
returns false. 

Second, DialogSelect does not check for the command key 
when handling key-down events. If some key-down events are 
special cases or if the command key equivalents for menu events 
(e.g., cut, copy, paste) are to be handled while the modeless 
dialog is the active window, then the modeless routine must 
check for key-down events prior to calling DialogSelect. The 
find/replace unitin the listing checks for edit menu command key 
equivalents, find/replace menu command key equivalents, and 
the return key as the default button. 


Find/Replace Routines 

Implementing a find/replace unit can take many alternative 
forms. Inside Mac does not specify user-interface guidelines for 
find/replace actions leading to many different solutions existing. 
The implementation given in the listing uses a single modeless 
dialog and follows a simple logic within three routines: Find, 
Search, and Replace. These routines provide the setup to access 
the toolbox routine Munger. Munger provides the core find and 
replace actions on the specified text. Switching between find and 
replace options alters the appearance and action of the modeless 
dialog. 


Logic Used 

When in the Find mode, the user can enter a text string 
(Figure 2). When the user clicks the find button (or presses the 
'return' key) the editText record is searched forward from the 
current selection. If located, the find string is highlighted in the 
editText record. If the string is not in the current visible region, 
a call to TESelView scrolls the string into view (Figure 3). If the 
string is not found, then the machine beeps. 

When in the replace mode, the user must enter a find string 
while the replace string is optional (Figure 4). When the user 
clicks the find button (or presses 'return"), starting at the current 
selection, the find routine tries to locate and highlight the find 
string. If found, the search routine changes the default button to 
‘Replace’ (Figure 5). When the user clicks the replace button (or 
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Figure 3 


presses ‘return’) the find text is replaced with the replace text, 
leaving the current selection after the replacement text, and re- 
establishing the ‘Search’ button as the default button (Figure 6). 
How It Works: Munger 

The find, search, and replace routines serve to setup the 
proper information to send to and retrieve from the toolbox 
function Munger: 
" é File Edit Search k 
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function Munger(h:handle; offset:longint; ptri: ptr; lent: 
longint; 
ptr2: ptr; len2: longint): longint. 

The handle, h, specifies a handle to destination text gener- 
ated as a relocatable block allocated by the memory manager. 
Offset refers to the starting location of the operation in the 
destination text and must be less than the length of the destination 
text. Ptr1, len refers to the target text and ptr2, len2 refers to the 
replacement text. The function value returned is negative if the 
operation failed and positive if the specified operation was 
successful. The behavior of Munger depends on the values 
passed. The six possible cases are: 

Case 1: ptr1«»nil, len1>0; ptr2<>nil, len2>0: the destina- 
tion text is searched from the offset specified to the end of the text, 
replacing the first occurrence of the target string found with the 
replacement text. The function returns the offset of the first byte 
past the replaced text. 

Case 2: ptr1=nil, len1>0; ptr2<>nil, len2>0: the destination 
text from the specified offset to offset + len1 is replaced by the 
replacement text. The function returns the offset of the first byte 
past the replaced text. | 

Case 3: ptrl=nil, len1<0; ptr2<>nil, len2>0: the destination 
text from the specified offset to the end of the destination text is 
replaced by the replacement text. The function returns the offset 
of the first byte past the replaced text. 

Case 4: len1=0; ptr2<>nil, len2>0: the replacement text is 
inserted into the destination text at the specified offset. The 
function returns the offset of the first byte past the replaced text. 

Case 5: ptr1<>nil, len1>0; ptr2-nil: the destination text is 
searched for the target string. Munger returns the offset at the 
beginning of the found string. 

Case 6: ptr1«»nil, Іепі>0; ptr2<>nil, len2=0: the target 
string is deleted from the destination text instead of replaced. The 
function returns the offset at the byte where the text was deleted. 


The find routine uses Case 5 to perform the search. The find 
routine retrieves the find string from the dialog, checking for a 
target string of length greater than zero. The replace pointer is set 
to nil. If the current selection is not an insertion point, the offset 
is set to the end of the current selection for the find dialog. The 
target length is retrieved and the replace length is set to zero. 
Finally, Munger is called. If the target string is found, the current 
selection is set to the target and scrolled into view. 

The search routine locates the target string using the find 
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routine. If the find was successful, then the default button is set 
to the replace button and enabled. Once the target string is 
located, a user action to replace call the replace routine. The 
replace routine uses Case 1 for positive length replacement text 
and Case 6 for empty replacement text. The replace routine 
retrieves the target and replace text from the dialog edit fields, 
sets the offset to the current selection start of the destination text, 
and finally calls Munger. If Munger returns a positive value, the 
first occurrence of the target text was replaced. The editText is 
then recalibrated, the selection reset, and an invalrect call used to 
force an update of the editText window. Finally, the default 
button is set back to the Search button. If Munger returns a 
negative value, the replace failed and the machine beeps. 


Concluding Remarks 

The find/replace unit presented is simple in design, takes 
very little additional memory (approximately 5k), easily inte- 
grated into your application, and easily modified to suit your 
tastes. Most all the programming work is setting up the call to 
Munger and interpreting the results. The routine could also be 
changed to a modal dialog quickly. However, the modeless 
dialog environment seems more natural for a find/replace capa- 
bility. 
Listing: EnvironIntf.p 
( File: EnvironsIntf .p) 


( Copyright Apple Computer, Inc. 1987) 
( All Rights Reserved) 


UNIT EnvironsIntf ; 


INTERFACE 
CONST 
envMac = -1; (returned by glue, if any) 
envXL = -2; (returned by glue, if any) 
envMachUnknown = 0; 
епу5 12КЕ = 1; 
envMacP lus = 2; 


envSE = 3; 

envMacII = 4; 

envCPUUnknown = 0; ( CPU types } 
env68000 = 1; 

епу68010 = 2; 

env68020 = 3; 

envUnknownKbd = Ø; ( Keyboard types ) 


envMacKbd = 1; 
envMacAndPad = 2: 


envMacP lusKbd = 3; 
envAExtendKbd = 4; 
envStandADBKbd = 5; 
( Errors ) 


envNotPresent = -5500; ( returned by glue. Official stuff) 
envBadSel = -5501; ( Selector non-positive ) 
envSelTooBig = -5502; ( Selector bigger than call can take) 


TYPE 
SysEnvRec - RECORD 

environsVersion : INTEGER; 
machinelype : INTEGER; 
systemVersion : INTEGER; 
processor : INTEGER; 
hasFPU : BOOLEAN; 
hasColorQD : BOOLEAN; 
keyBoardType : INTEGER; 
atDrvrVersNum : INTEGER; 
sysVRefNum : INTEGER; 
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END; 


FUNCTION SysEnvirons (versionRequested : INTEGER; 


VAR theWorld : SysEnvRec) : 


IMPLEMENTATION 
FUNCTION SysEnvirons; 
External; 

END. 


Listing Globals.Pas: 
UNIT SearchGlobs; 


(File name:Globals.Pas) 


OSErr; 


(Function: Global Variables and Constants for Search Program) 


dno 7/02/88 MEM Initial Variables Added. 
) 


INTERFACE 


USES 
ROM85; 
CONST 
(window constants) 
minWidth = 80; 
minHeight = 80; 


mBarHeightGlob = $BAA; 


sBarWidth 
TxtMargin 
TxtWindID 
AboutID = 
AlertID - 
I_OK = 1; 
SpeechID = 100; 
(Menu Resource 1075) 
AppleID = 201; 
FileID = 202; 
EditID = 203; 
SearchID = 204; 
(Menu Choice Constants) 
I_About = 1; 
I_Quit = 1; 
I_Undo = 1; 
I_Cut = 3; 
I_Copy = 4; 
I.Paste = 5; 
I Clear = 6; 
I.Find = 1; 
T_Replace = 2; 
I Show Text = 4; 
(Global Variables) 
VAR 
(nisc stuff) 
doneFlag : boolean; 


4 


4; 
2; 
0; 


ON Il 


we 


mBarHeight : integer; 


{menu stuff} 


AppleMenu : MenuHandle; 
FileMenu : MenuHandle; 
EditMenu : MenuHandle; 
SearchMenu : MenuHandle; 


(rectangles) 
DragRect : Rect; 
GrowRect : Rect; 
ScreenRect : Rect; 
TempRect : Rect; 
(window stuff) 


MyWindow : WindowPtr; 


(text edit stuff) 
hte : TEHandle; 
(String stuff) 
theString : Str255; 


IMPLEMENTATION 
END. 
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Listing: Inits.Pas 

UNIT Inits; 

(File name:Init.Pas) 

(Function: Initialization Routines for Search Program) 
(History: 7/82/88 MEM All routines Added. 


INTERFACE 
USES ROM85, EnvironsIntf, SearchGlobs; 


PROCEDURE InitMac; 
PROCEDURE CheckEnvirons; 
PROCEDURE InitTxtWind; 
PROCEDURE InitRects; 
PROCEDURE InitMenus; 


IMPLEMENTATION 
PROCEDURE Crash; 
BEGIN 

ExitToShell; 
END; 


PROCEDURE InitMac; 

BEGIN 
MoreMasters; 
MoreMasters; 
MoreMasters; 
initCursor; 
FlushEventsCeveryEvent, 0); 
doneFlag := false; 

END; 


PROCEDURE CheckEnv irons; 
VAR 
MyWorld : SysEnvRec; 
Version : integer; 
Erri, Err2 : OSErr; 
BEGIN 
Version := 1; 
Erri := SysEnvirons(Version, MyWorld); 
IF (MyWorld.machineType < 1) THEN 
BEGIN 
ParamText( ‘Program Requires Мас 512Ke or newer 
machine’, 4”, °’, 49; 
Err2 := NoteAlertCAlertID, NIL); 
ExitToShe11; 
END; 
END; 


PROCEDURE InitRects; 
VAR 
MemPtr : ^Integer; 
BEGIN 
MemPtr := pointer (MBarHeightGlob); 
mBarHeight := MemPtr^; 
screenrect := ScreenBits.Bounds; 
SetRect(DragRect, ScreenRect.left + 4, Screenrect.top + 


mBarHeight + 4, Screenrect.right - 4, Screenrect.bottom - 4); 


SetRect(GrowRect, ScreenRect.left + minWidth, 
Screenrect.top + minHeight, Screenrect.right - 8, 
Screenrect bottom - 8); 


END; 
PROCEDURE InitTxtWind; 
VAR 
ItemHdl : Handle; 
BEGIN 


MyWindow := GetNewWindow(TxtWindID, NIL, Pointer(-1)); 
SelectWindowCMyW indow ) ; 

Se tPor t(MyW indow); 

WITH MyWindow^.portRect 00 


SetRect(TempRect, 0, 0, right - sBarWidth - 1, bottom - 


sBarWidth - 1); 
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InsetRect(TempRect, TxtMargin, TxtMargin); 
hte := TENewCTempRect, TempRect); 
HLockCHandleChte)); 
hte^^.txFont := geneva; 
hte^^.fontAscent := 12; 
hte^^.lineHeight := 12 + 3 + 1; (ascent + descent + 
leading) 
HUnLockCHandleChte2); 
ItemHdl := GetResourceC'TEXT^, SpeechID); 
IF ItemHd] = NIL THEN 
BEGIN 
theString := ‘Search and Replace Demo program. Use 
find and replace to change text in this window. ’; 
TESetTextCPointerCOrd4CétheString) + 1), 
length(theString), hte); 
END 
ELSE 
BEGIN 
DetachResource(I temHd1 ); 
SetHandleSizeChte^^.hText, SizeResourceCItemHdl2); 
hte^^.hText := ItemHd!; 
hte**.teLength := SizeResourceCItemHd!); 
ReleaseResource( I temHd1); 
END; 
TESetSelect(0, 0, hte); 
TECalTextChte); 
TEAutoViewCtrue, hte); 
TESelViewChte); 
TextFontCapplFont); 
END; 


PROCEDURE InitMenus; 
VAR 
tempMenu : MenuHandle; 
BEGIN 
ClearMenuBar ; 
tempMenu := GetMenuCAppleID); 
AddResMenu(tempMenu, ‘DRVR’); 
InsertMenu(tempMenu, 0); 
AppleMenu := tempMenu; 
tempMenu := GetMenu(FileID); 
InsertMenuCtempMenu, 02; 
FileMenu := tempMenu; 
tempMenu := GetMenuCEditID); 
InsertMenuCtempMenu, 0); 
EditMenu := tempMenu; 
tempMenu := GetMenu(SearchID); 
InsertMenuCtempMenu, 0); 
SearchMenu := tempMenu; 
DrawMenuBar ; 
DisableItemCEditMenu, I.Undo); 
END; 


END. 


Listing: Utils.Pas 


UNIT Utils; 

(File name:Utils.Pas) 

(Function: General Utility Routines for Search Program) 
n) 7/02/88 MEM P Error Routine Added. ) 


INTERFACE 
USES ROM85, SearchGlobs, Find_Dialog; 


PROCEDURE Do-About; 

PROCEDURE Do.Menu СіһеМепу, theItem : integer); 
PROCEDURE FrameDItem CdLog : DialogPtr; iNum : integer); 
PROCEDURE Update. Txt; 

PROCEDURE Act.Txt (theEvent : EventRecord); 

PROCEDURE FixText; 

PROCEDURE Grow.Txt ChSize, vSize : integer); 
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PROCEDURE Do_Quit; 


IMPLEMENTATION 
PROCEDURE Do_About; 
VAR 
oldPort : GrafPtr; 
dig : DialogPtr; 
itemHit : integer; 
BEGIN 
GetPortCOldPort); 
919 := GetNewDialog(AboutID, NIL, pointer(-1)); 
FremeDItemCdlg, I_0K); 
ModalDialog(NIL, itemHit); 
DisposDialog(dlg); 
setPort(OldPort); 
END; 


PROCEDURE Do_Menu; 
VAR 
DaNum : integer; 
Bool : boolean; 
DAName : Str255; 
oldPort : GrafPtr; 
BEGIN 
CASE theMenu OF 
AppleID : 
BEGIN 
CASE theItem OF 
T_About : 
BEGIN 
бо. About; 
END; 
OTHERWISE 
BEGIN 
GetPortColdPort); 
GetItemCAppleMenu, theItem, DAName); 
DaNum := OpenDeskAcc(DAName); 
SetPortColdPort); 
END; 


BEGIN 
CASE theItem OF 
I Quit : 
doneFlag := TRUE; 
OTHERWISE 
BEGIN 
END; 
END; 
END; 
EditID : 
BEGIN 
IF NOT SystemEditCtheItem - 1) THEN 
BEGIN 
CASE theItem OF 
I.Cut : 
TECutChte); 
I-Copy : 
TECopyChte); 
I_Paste : 
TEPasteChte); 
I_Clear : 
TEDeleteChte); 
OTHERWISE 
BEGIN 


END; 
SearchID : 
BEGIN 
CASE theItem OF 
I.Find : 
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Open.F indCI.F ind); 
I-Replace : 

Open. F indCI. Replace); 
I-Show Text : 

BEGIN 
ShowWindowCMyWindow); 
se lectWindowCMyWindow); 

END; 

OTHERWISE 

BEGIN 

END; 

END; 
END; 
OTHERWISE 
BEGIN 
END; 
END; 
HiliteMenuC0); 
END; 


PROCEDURE FrameDItem; 
VAR 
iBox : Rect; 
iType : integer; 
iHandle : Handle; 
oldPenState : PenState; 
oldPort : GrefPtr; 
BECIN 
GetPortColdPort); 
SetPort(dlog); 
GetPenStateColdPenState); 
GetDItemCdLog, iNum, iType, iHandle, 
InsetRectCiBox, -4, -4); 
PenSize(3, 3); 
FrameRoundRect(iBox, 16, 16); 
SetPenStateColdPenState); 
SetPortColdPort) 
END; 


PROCEDURE UpDate. Txt; 
VAR 
oldPort : GrafPtr; 
BEGIN 
GetPortColdPort); 
SetPortCMyWindow); 
BeginUpDateCMyW indow); 
TEUpdateChte^^.viewRect, hte); 
DrawGrowIconCMyW indow); 
EndUpDate(CMyW indow); 
SetPortColdPort); 
END; 


PROCEDURE Act. Txt; 
BEGIN 
SetPort(MuWindow); 
IF Odd(theEvent.modifiers) THEN 
BEGIN 
TEActivate(hte); 
DrawGrowIcon(MuWindow); 
DisableItemCEditMenu, I_Undo); 
END 
ELSE 
BEGIN 
TEDeactivate(hte); 
DrawGrowIcon(MuWindow); 
Enableltem(EditMenu, I_Undo); 
END; 
END; 


PROCEDURE FixText; 
BEGIN 
HLock(Handle(hte)); 
WITH hte^^ DO 
BEGIN 


iBox); 
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viewRect := MyWindow^.portRect; 
WITH viewRect DO 
BEGIN 
right := right - sBarWidth - 1; 


bottom := bottom - sBarWidth - 1; 
bottom := (bottom DIV lineHeight) * lineHeight 
END; 


destRect := viewRect; 
InsetRect(destRect, TxtMargin, TxtMargin); 
TECalTextChte2; 
TESelViewChte2; 
END; 
HUnlock(HandleChte22; 
END; 


PROCEDURE Grow.Txt; 

BEGIN 
InvalRectC(MyWindow^ .por tRect ); 
EraseRect(MuWindow .portRect); 
SizeWindow(MyWindow, hSize, vSize, true); 
InvalRectCMyW indow^ .portRect); 
ҒіхТехі; 

END; 


PROCEDURE Do_Quit; 
BEGIN 
TEDisposeChte); 
DisposeWindowCMyWindow); 
ExitToShe11; 
END; 
END. (End of unit) 


Listing: Find.Pes 

UNIT Find-Dialog; 

(File name:Find.Pas  ) 

(Function: Handle a modeless dialog) 

(History: 7/03/88 MEM - Made the Find dialog functional 
INTERFACE 


USES ROMB5; 


PROCEDURE Init. Find; 
PROCEDURE Act.F ind; 
PROCEDURE Open.F ind (Action : integer); 


PROCEDURE Do_Find CtheEvent : EventRecord; hte : TEHandle); 


PROCEDURE Close.F ind; 


IMPLEMENTATION 
CONST 
FindID = 4; 
I.Find = 1; 


I-Replace = 2; 
I_Cancel = 3; 
I-Find_Label = 
I-Find_Text = 5; 
I_Replace_Label = б; 
I-Replace.Text = 7; 


Active = 0; 

InActive = 255; 

AlertID = 6; 
VAR 


MyDialog : DialogPtr; 
ExitDialog : Boolean; 
tempRect : Rect; 
DType : Integer; 

Index : Integer; 
DItem : Handle; 
CItem, CTempItem : controlhandle; 
itemHit : Integer; 
temp : Integer; 
Bolden : integer; 
Opened : integer; 
theString : Str255; 
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PROCEDURE FrameItem Cinum : integer); 
VAR 
iBox : Rect; 
iTgpe : integer; 
iHandle : Handle; 
oldPenState : PenState; 
oldPort : GrafPtr; 
BEGIN 
GetPortColdPort); 
SetPor t(MyDialog); 
GetPenStateColdPenState); 
GetDItemC(MyDialog, inum, iType, iHandle, iBox); 
InsetRectCiBox, -4, -4); 
PenSize(3, 3); 
FrameRoundRect( iBox, 16, 16); 
SetPenStateColdPenState); 
SetPortColdPort) 
END; 


PROCEDURE DeFrameItem Cinum : integer); 
VAR 
iBox : Rect; 
iType : integer; 
iHandle : Handle; 
oldPenState : PenState; 
oldPort : GrafPtr; 
BEGIN 
GetPortColdPort); 
SetPort(MyDialog); 
GetPenState(oldPenState); 
GetDItem(MyDialog, inum, iType, iHandle, iBox); 
InsetRectCiBox, -4, -4); 
PenSize(3, 3); 
PenMode(PatBic); 
FrameRoundRect(iBox, 16, 16); 
SetPenStateColdPenState); 


SetPortColdPort) 
END; 
PROCEDURE Init Find; 
BEGIN 

MyDialog := NIL; 
END; 


PROCEDURE Act_Find; 
BEGIN 
IF (MyDialog € NIL) THEN 
ShowWindow(MyDialog); 
END; 


PROCEDURE Open.F ind; 
VAR 
ThisEditText : TEHandle; 
TheDialogPtr : DialogPeek; 
BEGIN 
IF CMyDialog = NIL) THEN 
BEGIN 
MyDialog := GetNewDialog(FindID, NIL, Pointer(-1)); 
ShowWindow(MyDialog); 
SelectWindow(MyDialog); 
SetPor t(MyDialog); 
TheDialogPtr := DialogPeek(MyDialog); 
ThisEditText := TheDialogPtr^.textH; 
HLockCHandleCThisEditText 2); 
ThisEditText^^.txSize := 12; 
TextSize( 12); 
ThisEditText^^.txFont := systemFont; 
TextFontCsystemFont?); 
ThisEditText^^.txFont := 0; 
ThisEditText^^. fontAscent : ‚= 12; 
ThisEditText^^.lineHeight := 12 +3 + l; 
HUnLock(Handle(ThisEditText)); 
GetDItem(MyDialog, I_Replace_Text, DType, Ditem, 


tempRect); 
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SetlText(DItem, “70; 
SellText(MyDialog, I_Replace_Text, 0, 0); 
GetDItemCMyDialog, I.Find.Text, DTupe, DItem, 
tempRect); 
SetITextCDItem, ''); 
Sell Text(MyDialog, I.Find Text, 0, 0); 
Opened := action; 
Bolden := I.Find; 
END 
ELSE 
BEGIN 
Opened := action; 
selectWindow(MyDialog); 
END; 
IF (action = I FInd) THEN 
BEGIN 
DeFrameItemCI_Replace); 
HideDI tem(MyDialog, I_Replace); 
HideDItemCMyDialog, I_Replace_Label); 
HideDI tem(MyDialog, I_Replace_Text); 
GetDItem(MyDialog, I.Find, DType, DItem, tempRect); 
GetIText(DI tem, theString); 
SetCTitleCControlHandle(DItem), ‘Find’); 
SetWTitleCMyDialog, ‘Find’); 
Bolden := I_Find; 
END 
ELSE 
BEGIN 
ShowDI tem(MyDialog, I_Replace); 
SHowDI tem(MyDialog, I Replace.Labe!); 
SHowDItemCMyDialog, I_Replace_Text); 
GetDItem(MyDialog, I_Replace, DType, DItem, tem- 
pRect); 
HiLiteControl(ControlHandle(DItem), InActive); 
GetDItem(MyDialog, I Find, DType, DItem, tempRect); 
SetCTitle(ControlHandle(DI tem), ‘Search’); 
SetWTitle(MyDialog, ‘Replace’); 
END; 
DrawDialog(MuDialog); 
Frameltem(Bolden); 
ShowWindow(MuDialog); 
SelectWindow(MuDialog); 
END; 


PROCEDURE Close_F ind; 
BEGIN 
IF CMyDialog © NIL) THEN 
BEGIN 
DisposDialog(MyDialog); 
Opened := 0; 
MyDialog := NIL 
END; 
END; 


FUNCTION Find (hte : 
VAR 
theFindString : Str255; 
StartAt, EndAt, targetlen, replacelen, FoundAt : 


TEHandle) : boolean; 


longint; 
destText : Handle; 
targetPtr, replacePtr : Ptr; 
BEGIN 


Find := false; 
GetDItemCMyDialog, I.Find Text, Dtype, DItem, tempRect); 
GetI Text(DI tem, theFindString); 
IF CtheFindString = ‘’) THEN 
BEGIN 


temp := NoteAlert(AlertID, NIL); 


BEGIN 


destText := Handle(Chte^^.hText); 
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PeramText(C'You have not specified anything to Find’, 


targetPtr :- pointerCOrdCetheF indString2) + 1); 
replacePtr :- NIL; 
IF Chte^^.selStart < hte**.selEnd) THEN 

IF (opened = IL Find) THEN 


otartAt := hte^^.selEnd 
ELSE 
StartAt := hte^^.selStart 
ELSE 
StartAt := hte^^.selStart; 


targetlen := length(theFindString); 
replacelen :- 0: 
FoundAt := Munger(destText, StartAt, targetPtr, 
targetlen, replacePtr, replacelen); 
IF (FoundAt >= 0) THEN 
BEGIN 
TESetSelect(FoundAt, FoundAt + targetlen, hte); 
TESelView(hte); 
TEActivate(hte); 
Find := true; 
END 
ELSE 
SysBeep( 1); 
END ; 
END; 


PROCEDURE Replace Chte : 
VAR 
theFindString, theReplString : Str255; 
StartAt, EndAt, targetlen, replacelen, FoundAt : 


TEHandle); 


longint; 
destText : Handle; 
targetPtr, replacePtr : Ptr; 
OldPort : GrafPtr; 
BEGIN 


GetDI tem(MyDialog, I.Find Text, Dtype, DItem, tempRect); 

GetIText(DItem, theFindString); 

GetDI tem(MyDialog, I Replace.Text, Dtype, DItem, tem- 
pRect); 

GetIText(DItem, theReplString); 

destText :- Handle(hte^^.hText); 

targetPtr := pointer(Ord(@theFindString) + 1); 

targetlen :- lengthCtheF indStr ing); 

replacePtr :- pointerCOrdCetheReplString) + 1); 

replacelen := length(theReplStr ing); 

StartAt := hte^^.selStart; 


FoundAt := Munger(destText, StartAt, targetPtr, targetlen, 


replacePtr, replacelen); 
IF CFoundAt >= 0) THEN 
BEGIN 
TECalTextChte); 
TESetSelect(FoundAt, FoundAt, hte); 
TESelView(hte); 
GetPortCOldPort); 
SetPort(hte^*^. inPort); 
InvalRectChte^^ .viewRect); 
SetPortCOldPort); 
TEActivateChte); 
GetDItem(MgDialog, I.Replace, DTupe, DItem, tem- 
pRect); 
HiLiteControl(ControlHandle(DItem), Inactive); 
DeFrameItemCI. Replace); 
FrameItemCI.Find); 
Bolden := I.Find; 
END 
ELSE 
BEGIN 
sysbeep( 1); 
GetDItem(MyDialog, I_Replace, DType, DItem, tem- 
pRect); 
HiLiteControl(ControlHandle(DItem), Inactive); 
IF (bolden = I Replace) THEN 
DeFrameItemCI Replace); 
FrameItemCI.F ind); 
Bolden := I.Find; 
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END; 
END; 


PROCEDURE Search (hte : 
VAR 
theReplString : Str255; 
Success : boolean; 
BEGIN 
GetDItemCMgDialog, I_Replace Text, Dtype, DItem, tem- 
pRect); 
GetIText(DI tem, theReplString); 
success := FindChte); 
IF success THEN 
BEGIN 
GetDItem(MyDialog, I_Replace, DType, DItem, tem- 


TEHandle); 


pRect); 
HiLiteControl(ControlHandle(DItem), Active); 
DeFrameItemCI.Find); 
Framel tem(I_Rep lace); 
Bolden := I_Replace; 
END; 
END; 


PROCEDURE Do_Find; 

CONST 
ReturnKey = 13; 

LABE 
1; 

VAR 
Index : integer; 
myPt : Point; 
ExitDialog : boolean; 


CmdDown : boolean; 

success : boolean; 

chCode : integer; 

MyCmdKey : char; 

whichDialog : DialogPtr; 
BEGIN 


ExitDialog := false; 
IF (MyDialog © NIL) THEN 
BEGIN 
IF CtheEvent.what = KeyDown) THEN 
BEGIN 
CmdDown := odd(theEvent.modif iers DIV CmdKey); 
chCode := BitAndCtheEvent.message, CharCodeMask); 
MyCmdKey := CHRCchCode); 
IF CmdDown THEN 
BEGIN 
IF ((MuCmdKeu = ‘x’) OR CMyCmdKey = ‘X’)) 
THEN 
DigCut(MyDialog) 
ELSE IF CCMyCmdKey = ‘c’) OR СМуСтакеџ 


'C^)) THEN 
D1gCopyCMgDialog? 
ELSE IF ((MuCmdKeu = ‘v’) OR (MuCmdKeu 


'V^)) THEN 
DigPaste(MyDialog) 
ELSE IF ((MuCmdKeu = ‘f’) OR CMyCmdKey 


'F^)) THEN 
Open.F indCI.F ind) 
ELSE IF ((MuCmdKeu = ‘r’) OR CMyCmdKey 


'*R^)) THEN 
Open.F indCI. Replace?; 
GOTO 1 
END 
ELSE IF CchCode = ReturnKey) THEN 
BEGIN 
IF (bolden = I_Find) THEN 
IF (Opened = I_Find) THEN 
success Find(hte) 
ELSE 
Search(hte) 
ELSE 
Replace(hte); 
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END; 
IF DialogSelect(theEvent, whichDialog, itemHit) THEN 
BEGIN 
GetDItemCwhichDialog, itemHit, ОТуре, DItem, 
tempRect); 
CItem := Pointer(DI tem); 
IF CItemHit = I_Cancel) THEN 
ExitDialog := true; 
IF CItemHit = IFind) THEN 
IF (Opened = I_Find) THEN 
success := Find(hte) 
ELSE 
Search(hte); 
IF (ItemHit = I_Replace) THEN 
Replace(hte); 
END 
ELSE IF (theEvent.what = UpDateEvt) THEN 
Frameltem(Bolden) 
ELSE IF (theEvent.what = ActivateEvt) AND (Opened = 
IFind) AND Odd(theEvent.modifiers) THEN 
BEGIN 
GetDItem(MyDialog, I-Find, DType, DItem, tem- 
pRect); 
GetIText(DI tem, theString); 
IF lengthCtheString) > Ø THEN 
SellText(MyDialog, I_Find_Text, Ø, 
length(theString)); 
END; 
END; 


IF ExitDialog THEN 
BEGIN 
Close.F ind; 
END; 
END; 


END. 


Listing: Search.Pas 

PROGRAM Searcher; 

(Program name:Searcher.Pas  ) 

(This is the main program and event loop. ) 
ші 7/03/88 МЕМ Шы Coding ) 


USES 
ROM85, SearchGlobs, Inits, FindDialog, Utils; 
VAR 
theEvent : EventRecord; 
thecode : integer; 
theWindow : WindowPtr; 
thePeek : WindowPeek; 
OldPort : GrafPtr; 
menuResult : longint; 
newSize : longint; 
theMenu, theltem : 
chCode : integer; 
ch : char; 
GlobalPt, localPt : Point; 
EventFlag : boolean; 
extend : boolean; 
BEGIN 
InitMac; 
InitRects; 
InitMenus ; 
InitTxtWind; 
Init. Find; 
REPEAT 
IF (hte © NIL) THEN 
TEIdleChte); 
SystemTask ; 
EventFlag := GetNextEventCeveryEvent, theEvent); 
thecode := FindWindow(theEvent where, theWindow?; 


integer; 
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IF IsDialogEvent(theEvent) THEN 
Do_Find(theEvent, hte) 
ELSE IF EventFlag THEN 


BEGIN 
CASE theEvent.what OF 
MouseDown : 
BEGIN 
IF Cthecode = inMenuBar) THEN 

BEGIN 
menuResult := MenuSelectCtheEvent Where); 
theMenu := HiWord(menuResult); 
theltem := LoWord(menuResult); 
Do_Menu(theMenu, theItem); 

END; 


IF (thecode = InDrag) THEN 
DragWindow(theWindow, theEvent.where, 


DragRect); 
IF (thecode = inGrow) THEN 
BEGIN 
newSize := GrowWindow(theWindow, 


theEvent.where, GrowRect); 
IF newSize <> 0 THEN 
Grow. TxtCLoWordCnewS ize), 


HiWord(newSize)) 
END; 
IF Cthecode = inGoAway) THEN 
BEGIN 
IF TrackGoAwagCtheWindow, theEvent.where) 
THEN 


HideWindow( theWindow); 
END; 
IF CCthecode = inZoomIn) OR Cthecode = 
inZoomOut)) THEN 
BEGIN 
IF TrackBox(thewindow, theEvent.where, 
theCode) THEN 
BEGIN 
GetPortCOldPort); 
SetPor t CMyW indow); 
EraseRect(MyWindow^ .portRect); 
ZoomWindow(Mgwindow, thecode, TRUE); 
WITH MyWindow^.portRect DO 
Grow_TxtCright - left, bottom - 


top); 
SetPortCOldPort); 
END; 
END; 
IF Cthecode = inContent) THEN 
BEGIN 


IF CtheWindow O FrontWindow) THEN 
Se lectWindow( theW indow) 
ELSE 
BEGIN 
globalPt := theEvent .where; 
localPt := globalPt; 
GlobalToLocal(ClocalPt); 


IF PtInRectClocalPt, hte^^.viewRect 
THEN 
BEGIN 
extend := 
(BitAnd(theEvent.modifiers, ShiftKey) © 0); 
TEClickClocalPt, extend, hte); 
END; 
END; 
END; 
IF Cthecode = inSysWindow) THEN 
SystemClickCtheEvent, theWindow); 


END; 
KeyDown, AutoKey : 
BEGIN 
WITH theEvent DO 
BEGIN 
chCode := BitAnd(message, CharCodeMask); 


ch := CHR(chCode); 
IF COdd(modif iers DIV CmdKey)) THEN 


BEGIN 
menuResult := MenuKey(ch); 
theMenu :- HiWordCmenuResult); 
theltem := LoWord(menuResult); 


IF CtheMenu <> Ø) THEN 
Do_Menu(theMenu, theItem) 


) 


ELSE IF ((ch = x’) OR (ch = ’X’)) AND 


(hte € NIL) THEN 
TECutChte) 
ELSE IF (Cch = 'c^) OR (ch 


(hte © NIL) THEN 
TECopyChte) 


"722 AND 


ELSE IF (Cch = ‘v’) OR (ch = 'V/)) AND 


(hte © NIL) THEN 
TEPasteChte); 
END 
ELSE IF (hte © NIL) THEN 
TEKeyCch, hte); 
END; 
END; 
UpDateEvt : 
BEGIN 
Update_Txt; 
END; 
ActivateEvt : 
BEGIN 
Act_Ixt(theEvent); 
END; 
OTHERWISE 


END; 
UNTIL doneF lag; 
Do. Quit; 
END. 


ee eee 
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Pascal Procedures 


Have Your Window Do The Splits 


Split Personality 
As I was looking in chapter two of Inside Macintosh, Vol. I, 
I saw a Sweet little interface under the heading “Splitting a 
Window.” I thought about that interface and decided it would be 
nice to create a split bar in a window. So, I set out to write a 
control definition for the split bar and a short little demo to see 
what additional support was needed by the application. 


The Split Bar Interface 

A splitbar is used to divide a window into two or more views 
of adocument. The split bar creates and readjusts scroll bars on 
top and bottom of the split bar as itis moved. This allows the user 
to scroll each view, called a “pane,” to different areas (See Figure 
1). Many word processing and spreadsheet applications use split 
bars. 

For example, at program start up, there is one scroll bar and 
a black rectangle (the split bar) directly above it and beneath the 
drag bar of the window. The user then clicks on the split bar and 
drags it across the top of the scroll bar. As he releases the split 
bar, the scroll bar’s top is brought down on the screen just under 
the split bar again and another scroll bar above the split bar fills 
the space left by moving the split bar. As the user continues to 
move the split bar up or down, the top and bottom scroll bars are 
adjusted in height accordingly. 


The Split Bar CDEF 

The split bar functions like a scroll bar with only athumb. In 
some ways, it is easier than a normal scroll bar to create. For 
example, there is no concern for page up/down or line up/down— 
only a thumb routine (which is not very easy until you know 
how). I include two variations of the CDEF for both horizontal 
(1) and vertical (2) split bars. 

The CDEF for a split bar is somewhere between the com- 
plexity of a normal button and a scroll bar. If you read up on 
defining your own controls (Inside Macintosh, Vol. 1, Chapter 
10), there are nine routines that your control function may or may 
not need to handle. Most of the routines I, and others, have 
covered before in previous issues of MacTutor (Vol. 5, No. 1 and 
4). I will only examine those parts that apply to the split bar. 


calcCRgns Message 

This message asks the CDEF to calculate the region of the 
control or indicators and store it in the region handle supplied in 
the param parameter. Upon entry, you test param to see if the 
high bit is set. If it is, you give the region for the indicator, and 
if not, you give the region of the control. 

The region of the control is its enclosing rectangle. This 
rectangle extends the length of the window. This areais the same, 
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Splitbar Test Demo 


See Test Window See i === 
Splitbar available for those with split personalities 


Splitber available for those with split personalitied 


Figure 1. Demo Application 


except for a few areas, as the area the two scroll bars occupy. (See 
Figure 2). 


Split Bar 


Scroll Bar 


Scroll Bar 
Split Bar Thumb 


Figure 2 Scroll and Split Bars 


Stacking controls is not a good idea (how do you know 
which control you are in?). But, since the Split Bar CDEF only 
reports a mouse down in the indicator, which is not covered, we 
have no problem knowing which control was pressed. 

Now if the message wants the region of the thumb indicator, 
it is because it is about to be dragged around the screen with 
DragGrayRgn. Rather than just the region of the thumb, I 
decided to give additional, visual interface to the user by drag- 
ging a rectangular gray region across the window along with the 
thumb. In the application, I draw a couple lines across the screen 
to separate the panes, and this gives the feel that these two lines 
are part of the control. Calculating this other region is easy since 
all points are known. 


thumbOCntl Message 
This message is another routine used as a precursor to 
dragging an image of the thumb. The param parameter is a 
pointer to the following record: 
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thumbinfo = record; 
limitRect : Rect; 
trackRect : Rect; 
axis : integer; 
end; 


Thisrecord hasthe same meaning as that of the DragControl 
procedure. limitRect confines the movement of the indicator 
itself; trackRect defines the rectangle where the indicator will 
track with the mouse (these two are just the control’s rectangle); 
and axis determines tracking constraints— 1 for horizontal, 2 for 
vertical, and 0 for none. Notice that the axis constraints are the 
same as the variation of the control (I did not implement a 0 
variation). 


posCntl Message 

After the thumb has been dragged all over, the CDEF is 
called again with a posCntl message to reposition the thumb. 
You must erase the old position of the indicator which I do with 
a flag sent to my draw routine and invalidating the place where 
the indicator was. 

The next step is to figure out the new value of the control. 
Our friend, param, is typecasted to a point and holds the relative 
offset both horizontal and vertical. The new value of the control 
is the old value plus the offset, minus any amount that goes out 
of bounds. Finally, the control is drawn at its new value. 


Other Messages 
The initCntl message just sets the contrlAction field of the 
control to nil. The drawCntl message holds nothing mysterious 
that hasn't been covered before. There is nothing done for the 
dispCntl, dragCntl, and autoTrack messages. The latter two 
messages are for further customizing your control. 


The Split Bar Demo 

I decided to write a simple Text Edit demo using a vertical 
split bar. The user could pull the split bar up and down, resize the 
window, scroll each pane independently, do editing in either 
pane, and see updates if applicable in both panes. This was 
certainly a mouthful. 

I tried to think about how to handle text in the two panes. I 
could keep two Text Edit records identical except for view and 
destination rectangles, or I could use one record and just switch 
the view and destination rectangles when needed. I decided to 
implement the latter version. Although separate TE records 
would have made it simpler to develop and not taken too much 
memory, I thought that this demo could have easily been a 
spreadsheet or a drawing application where the document might 
be too much to duplicate (what if there were a possibility of four 
or even nine panes?). 

The next step was to readjust the view rectangles and scroll 
bars when the split bar was moved. Since the value of the split 
bar control was in pixels, this presented no problems. I just 
adjusted the bottom of the top TE view rectangle by the split bar 
value and the lower TE view rectangle by split bar value and the 
indicator width. I also did the same with the scroll bars. In fact, 
I used the same routines to fix the view rectangles and scroll bar 
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heights when the window was grown as when the split bar was 
moved. 

There was the problem of when the height of the scroll bar 
was less than what was needed to draw the scroll bar properly. So 
if the height was smaller, I made the control invisible. I also 
restricted the growing of the window as to leave a minimum 
space from the split bar. Therefore, if the height did not allow a 
scroll bar to be drawn correctly, it was not drawn, and the user 
could not scroll that pane. 

Besides responding to the grow and split bar, each pane must 
respond to editing such as cut, copy, paste, and keyboard input. 
The standard procedure is used in the active pane and then the 
other pane is invalidated to take care of updating in the update 
procedure. 

The pane where the action such as scrolling and editing 
happens is quite easy to figure out. The scroll bars have a pane 
associated with it. They switch the TE record to the proper pane, 
scroll the TE record, and then reset the TE record back to the 
active pane. Mouse downs in the content region see which pane 
they are in and then switch the active pane. I also do automatic 
scrolling to the selection for the active pane only (the non active 
pane only moves when scrolled by its scroll bar or by major 
editing). 

The updating of the window is easy to accomplish. Simply 
switch panes and do a TEUpdate call to both panes. 

That is about it, the demo is pretty much your standard TE 
demo you have seen before. You simply switch the view and 
destination rectangles, duplicate or update the other, and then 
switch back to the active pane. You will also notice several 
TEActivates and TEDeactives throughout the source code. I 
found that the blinking insertion point would stay around if you 
switched between panes or typed while it was drawn. The 
solution was to turn it off, switch panes or edit, and then turn it 
back on. 


Improvements 

I limited the demo to a single, vertical split bar. To improve 
the demo, you could include a horizontal split bar making a 
possibility of four panes. You might even want to add multiple 
split bars to the horizontal and/or vertical dimensions. This could 
give you to nine panes if you have two horizontal and two vertical 
split bars. There would be the problem of keeping a split bar 
invisible if it was covered by another split bar. 

There is one minor bug I could not track down. On starting 
the demo after the Mac has been restarted, the indicator's outline 
isnot drawn when itis dragged. However, if youclick on the drag 
bar of the window, creating a window outline, then the indicator 
Outline appears from then on, until the Mac is restarted. I tried 
fixing this but could not do so. If any of the readers have any 
insight, please write me at MacTutor, and I'll relay the informa- 
tion in the letters column. 

The CDEF allows horizontal and vertical variations (1 and 
2). These numbers follow the axis constraints for dragging the 
thumb. How about a combined horizontal and vertical split bar 
which would have a variation code of 0 (no constraint)? This 
could beused for maybe a new and improved combined scrolling. 


355 


The CDEF could be used for other things such as T bars for 


drawing programs. 


All this is left as an “exercise to the reader.” Good luck! 
Now your windows will have the same type of personality as the 


developer— split. 


Listing: splitbar.pas 


unit MyControl; 

(Splitbar Code Definition Function - ID=17) 

(This creates two types of splitbar controls - horizontal,) 
( variation code 1; and vertical, variation code 2) 

(А Splitbar is essentially just an indicator (thumb) which) 
( can be moved by the mouse to set ) 

(up window panes. The control only moves the thumb. 
( up to the application to create/resize normal) 
(scrollbars, adjust the content region, and so forth. It) 
(will only return the Indicator part code of) 

(inThumb (129). There are no page/line up/down parts) 
(valid min is @ and max is screen width - indicatorwidth;) 
( control value is then in pixels) 

(To get a horizontal splitbar ask for CDEF 273 ( 16*ID + ) 
( variation), and 274 for vertical) 

(History) 

(3/15/89 Created by Kirk Chase) 


It is) 


interface 

( main entry into CDEF ) 

function main (varCode: integer; theControl: ControlHandle; 
message: integer; param: longint): longint; 


inplementation 
const 

vSplitBar = 2; (Variation code for a vertical splitbar) 
hSplitBar = 1; (Variation code for a horizontal splitbar) 
IndicatorWidth = 6; (width of thumb) 
PaneWidth = 4; 
draw = 1; 
erase = 0; 
invisible = 0; 
inactive = 255; 


function main; 


procedure doRect (varcode, value: integer; var theRect: 
rect); 
(calculate indicator rectangle according to varcode) 
begin 
case varcode of 
vSplitBer: 
begin 
theRect.top := value + theRect.top; 
theRect.bottom := theRect.top + IndicatorWidth; 
InsetRectCtheRect, 1, 0); 
end; 
hSplitBar: 
begin 
theRect.left := value + theRect. left; 
theRect.right := theRect.left + IndicatorWidth; 
InsetRectCtheRect, 0, 1); 
end; 
end; 
end; 


procedure doInit (myControl: ControlHandle); 
(inits control by setting the action proc to nil) 
begin 
myControl^^.contrlAction := nil; (set action proc ) 
end; (of doInit) 


procedure doDraw (varCode: integer; myControl: Control- 
Handle; flag: integer); 
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(this will draw or erase thumb control according to flag) 
var 
eRect, iRect: Rect; 
oldClip, controlRegion: RgnHandle; 
oldPen: PenState; 
begin 
(onlu draw if visible) 
14 (ngControl^^.contrlVis € invisible) then 
begin 
( Get control’s region & set clip region to region.) 
oldClip := NewRgn; 
GetClipColdClip); 


( Set the clip region to the control’s rectangle ) 
aRect := myControl**.contriRect; 
iRect := aRect; 
controlRegion := NewRgn; 
RectRgnCcontrolRegion, aRect); 
MoveHHiCHandle(mgContro122; 
HLockCHandleCmyContro12)2; 
SetClipCcontrolRegion); 
HUn lock CHandleCmyControl)); 


(set pen to normal state) 
GetPenStateColdPen); 
PenNormal; 


FrameRect(aRect); (draw control bounds) 
doRect(varcode, myControl^^.contrlValue, iRect); 


{either draw or erase indicator) 
if flag = draw then 
PaintRectCiRect) 
else 
EreseRectCiRect?; 


1f (nyControl^^.contrlHilite = inactive) then 
EraseRect(iRect); (inactive controls) 


SetClipColdClip); (Clean up) 
DisposeRgn(oldClip); 
DisposeRgn(controlRegion); 
SetPenStateColdPen); 
end; 
end; (of doDraw) 


function doTest (varcode: integer; myControl: Control- 
Handle; theParam: longint): longint; 
(returns inThumb or 0 if mousedown in thumb or not) 
var 
CRect, IRect: Rect; 
thePoint: point; 


begin 
CRect := myControl^^.contrlRect; (initialize values) 
IRect := CRect; 
thePoint := pointCtheParam); 
doTest := 0; 


(test point if active and visible) 
if (myControl^^.contrlHilite © inactive) and 
(mgControl^^.contrlVis O invisible) then 
begin 
(in control?) 
if PtInRectCthePoint, CRect) then 
begin 
(in thumb?) 
doRect(varcode, myControl^^.contrlValue, 
IRect); 
if PtInRect(thePoint, IRect) then 
doTest := inThumb; 
end; 


end; 
end; (of doTest) 
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procedure doCalc (varcode: integer; myControl: Control- 
Handle; theParam: longint); 
(calculate all or indicator’s region} 
var 
aRect: Rect; 
thumbRgn: RgnHandle; 
begin 
( CalcButtnRgn must first find out 1f high bit is set. ) 


( High bit set indicates that ы being calculated is) 


( for an indicator 
1f not BitTst(Ptr(ë8ëtheParam), Ø) then 
begin (whole region) 
theParam := longint(BitAnd(theParam, $@@FFFFFF)2); 
aRect := туСопіго1“° .contrlRect; 
RectRgn(RgnHandle(theParam), aRect); 


aRect := myControl^^.contrlRect; 
doRect(varcode, myControl^^.contrlValue, aRect); 
thumbRgn := NewRgn; 
RectRgnCthumbRgn, aRect); 
if varcode = vSplitBar then (get rgn ) 
SetRect(aRect, 0, aRect.top + 1, aRect.right, 
aRect.bottom - 1) (vertical splitbar) 
else 
SetRect(aRect, aRect.left + 1, 0, aRect.right - 
1, aRect.top); (horizontal splitbar) 
RectRgn(RgnHandle(theParam), aRect); 
UnionRgn(RgnHandle(theParam), thumbRgn, 
RgnHandle(theParam)); 
DisposeRgn(thumbRgn); 
end; 
end; (of doCalc) 


procedure doThumb (muControl: ControlHandle; varcode: 
integer; theParam: longint); 
(this sets up dragging parameters for thumb) 
type 
thumbPtr = ^thumbinfo; 
thumbinfo = record 
limitRect: Rect; 
trackRect: Rect; 
axis: integer; 
end; 
begin 
with thumbPtr(theParam)* do 
begin 
limitRect := myControl**.contr1Rect; 
trackRect := myControl**.contr Rect; 
axis := varcode; 
end; 
end; (of doThumb) 


procedure doPosition (myControl: ControlHandle; varcode: 


integer; DeltaPoint: longint); 
(this routine is called to reposition the control ) 
(first erase old position of control and draw in new place) 
var 
thePoint: point; 
value, delta, position: integer; 
aRect: rect; 
begin 
aRect := myControl^^.contrlRect; (get thumb region) 
doRect(varcode, myControl^^.contrlValue, aRect); 
InvalRectCaRect?; 
doDraw(varCode, myControl, erase); (erase) 


thePoint := point(DeltaPoint); 
value := myControl^^.contrlValue; 


if varcode = vSplitBar then (calculate delta offset) 
begin 
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positi 
delta 
end 
else 
begin 
positi 
delta 
end; 


on := value + thePoint.v; 
:= thePoint.v; 


on := value + thePoint.h; 
‚= thePoint.h; 


{recalculate delta offset if out of bounds) 
if position < myContro1^^.contrlMin then 


delta :- 


-Cvalue - myControl^^.contrlMin); 


if position > myControl^^.contr Max then 


delta := 


myControl**.contr1Max - value; 


myControl^^.contrlValue := myControl^^.contrlValue + 
delta; (reset control value) 


doDrawCvarCode, myControl, draw); (redraw) 
end; (of doPosition 


begin (main entry point) 
main := Ø; {initialize values) 


case message 
initOntl: 


of (switch to proper routine) 


doInitCtheContro1); 


drawCnt]: 


doDrawCvarCode, theControl, draw); 


testCnt 1: 


main := doTest(varcode, theControl, param); 


( Calc the region for the button. ) 


calcCRgns: 


doCalc(varcode, theControl, param); 


thumbCnt1: 


doThumbCtheControl, varcode, param); 


posCnt 1: 


doPositionCtheControl, varcode, param); 


( Nothing to do for these messages... } 
dragCntl, autoTrack, dispCnt1: 


otherwise 
end; 
end; 


end. (of MyControl Unit) 


Listing: MyGlobals.pas 


unit MyGlobals; 
interface 
const 


Splitbar = 10; (Scroll bar ID) 


Scrollbar2 
Scrollbar 1 


9; (Scroll bar ID) 
8; (Scroll bar ID) 


SBarWidth = 16; (ScrollBr Width) 


AppleMenuID = 


1; (Menu list) 


About_Splitbar = 1; 


FileMenuID = 
C_New = 1; 
C_Close = 3; 
C_Quit = 5; 
EditMenuID = 
C_Undo = 1; 
C Cut = 3; 
C_Copu = 4; 
C_Paste = 5; 
SBarMinLen = 
CR = Chr(13); 


2; (Menu list) 


3; (Menu list) 


55; (Min. Scroll bar hieght to be usable} 
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VSpiltbar = 274; (variation code for split bar) 
IndicatorWidth = 6; (split bar width) 

Margin = 4; (margin inset for TE) 
AboutDialogID = 1; (about dialog ID) 

WindowID = 2; (MuWindow ID) 

About_OK = 1; (OK button in About Dialog) 
invisible = 0; 

visible = 255; 

inactive = 255; 
active = 0; 


mBarHeightGlobal = $BAA; (location of menu bar height) 
WNETrapNum = $60; 

UnImplTrapNum = $9F; 

MultiEvt = 15; 

bit® = 31; 

GrayRgnLowMemGlobal = $9EE; 


var 


Scroll: array{1..2] of ControlHandle; (scrollbars) 
Split: ControlHandle; (splitbar control) 


MyWindow: WindowPtr; 


viewRect: array[1..2] of rect; (TE viewRects switching) 
destRect: array[1..2] of rect; (TE destRects switching) 


end 
end; (of LinesInText) 


procedure AdjustScrollBars; (reset max of scroll bars) 
var 
ctlMax, index, height: integer; 
begin 
for index := ! to 2 do (for each pane) 
begin 
SetEditTextCindex2; (set pane) 
with EditText^^ do 
begin 
height := (viewRect.bottom - viewRect.top) div 


lineHeight; (lines of text in viewRect) 


ctlMax := LinesInText - height; (Control max) 
1f ctlMax < 0 then 
ctlMax := 0; 
SetCtlMaxCScrolltindex], ctlMax) 
end 
end; 
SetEditText(activePane); (reset back to active pane) 
end; (of AdjustScrollBars) 


procedure AdjustText; (scroll to scrollbar value) 
var 
oldScroll, newScroll, delta: integer; 


activePane: integer; (active pane where insertion pt is) begin 
setEditText(pane); 
EditText: TEHandle; (the TE record for the editing) with EditText** do 
begin 
paneRect: rect; (the two lines that split the pane) dp ‚= viewRect.top - destrect.top; (get old ) 
newScroll := GetCtlValueCScrollípanel) * lineHeight; 
AppleMenuHandle, FileMenuHandle, EditMenuHandle: (get new scroll value) 
MenuHandle; (various menu handles) delta := oldScroll - newScrol!; 
if delta © 2 then 
theWorld: SysEnvRec; begin 
theErr: OSErr; TEScrol1(@, delta, EditText); (scroll to new ) 
WNE: boolean; end; 
mBarHeight: integer; end, 
implementation destRect[panel := EditText^^.destRect; (reset destRect ) 


end. SetEditTextCactivepane); (reset to active pane) 
end; (of AdjustText) 
Listing: MyScroll.pas 


procedure ScrollCharacter; (scroll selection into view) 


unit MuScroll; var 
interface theLine, height: integer; 
uses begin 
MyG lobals; HLockCHandleCEditText)); 


theLine := 0; 
procedure AdjustScrollBars; (reset max of scroll bars) with EditText^^ do 
procedure AdjustText (pane: integer); (scroll to value) begin 
procedure ScrollCharaecter; (scroll selection into view) height := (viewRect.bottom - viewRect.top) div 
procedure ScrollToSelection; ( figure which way to scroll) lineHeight; 
procedure SetEditText (Index: integer); (Switch TE pane) while selStart >= lineStartsttheL ine] do 
procedure FixTextRects; (resize EditText’s rectangles) theLine := theLine + 1; 
procedure FixScrollbarRects; (resize & post scroll/split ) SetCtlValueCScrolllactivePane], theLine - nLines div 
procedure UpdateOtherPane; (inval nonactivepane’s update ) 2); 
AdjustTextCactivePane); 
implementation end; 
HUnLockCHandleCEditText)); 
( This is taken from Symantec’s Think’s Pascal} end; {of scroll character} 
function LinesInText: integer; 


var procedure ScrollToSelection; (way to scroll to select) 
lines: integer; var 
txt: CharsHandle; topline, bottomline, height, max: integer; 


begin begin 
with EditText** do SetEditTextCactivePane); 
begin HLockCHandleCEditText)); 
lines := nLines; AdjustScrollBars; 
txt := CharsHandleChText); AdjustTextCactivePane); 
if teLength > 0 then with EditText^^, viewRect do 


if txt**(teLength - 1] = CR then (Return?) begin 
lines := lines + 1; topline := GetCtlValueCScroll[activePane 10; 
LinesInText := lines height := (bottom - top) div lineHeight; 
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bottomline := topline + height; 
max := GetCtlMax(Scroll[lactivePane]); 
if max = Ø then (811 text within pane) 
AdjustTextCactivePane) 
else 
ScrollCharacter; (need to scroll) 


end; 
HUnLockCHandleCEdi tText 22; 
end; (of ScrollToSelection) 


procedure SetEditText; 
(Set EditText to indexed pane) 
begin 
EditText^^.viewRect := viewRect[Index]; 
EditText^^.destRect := destRect[Index]; 
end; (of SetEditText) 


procedure FixTextRects; (adjust EditText’s two panes) 
begin 
HLockCHandleCEditText22); 
viewRect[1] := MyWindow^.portRect; (set lower pane) 
viewRect[11.top := Split^^.contrlValue + IndicatorWidth; 
viewRect[1].right := viewRect[1].right - SBarWidth; 
viewRect[1].bottom := viewRect[1).bottom - SBarWidth; 
InsetRect(viewRect[1), Margin, Margin); (Give TE margins) 


(Make viewRect a Multiple of lineHeight) 
viewRect[1].bottom := viewRect[1].bottom - 
(CviewRect[1].bottom - viewRect[1].top) mod 
EditText^^.lineHeight?; 
destRect[1] := viewRect[1]; (Set destRect) 


viewRect{2] := MyWindow^.portRect; (set upper pane) 
viewRect[2].bottom := Scrol1[21^^.contrlRect bottom; 
viewRect[2].right := viewRect[2].right - SBarWidth; 
InsetRect(viewRect[2], Margin, Margin); (Give TE margins) 


(Make viewRect a multiple of lineHeight) 
viewRect[2].bottom := viewRect[2].bottom - 
(CviewRect[2].bottom - viewRect[2).top) mod 
EditText^^.lineHeight2; 
destRect[2] := viewRect[2]; 


SetEditText(activePane); (Reset back to active pane) 


if EditText © nil then (recalculate line starts) 
begin 
TECalTextCEditText); 
AdjustTextC 12; 
AdjustText(2); 
ScrollToSelection; 
end; 
HUnLockCHandleCEdi tText22; 
end; (of FixTextRects) 


procedure FixScrollbarRects; (Fix scrollbars to splitbar) 
var 
width, hieght: integer; 
temp: rect; 
begin 
with MyWindow^.portRect do (get window dimensions) 
begin 
hieght := bottom - top - SBarWidth + 1; 
width := right - left - SBarWidth + 1; 
end; 


SetRect(temp, width, Ø, width + SBarWidth, hieght); 

Split^^.contrlRect := temp; 

scroll(1]** .contriRect := Split^^.contrlRect; 

Scrol1[21]^^.contrlRect := Split**.contrlRect; 

Scroll[1]^^.contriRect.top := Split^^.contrlValue + 
IndicatorWidth; 

Scro11[(21^^.contrlRect.bottom := Split^^.contrlValue; 
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(check to see if there is enough room to draw scroll! bars) 


if (Scro11[21^^.contrlRect.bottom - 
Scro11[2]^^.contrlRect.top) < SBarMinLen then 
begin (not enough room, make invisible) 
EraseRect(Scro11I21^^.contrRect?); 
Scroll(2]^^.contrlVis := invisible; 
end 
else (enough room, make visible) 
5сг01112177.сопіг1Уі5 := visible; 


if (Scrol1([1]**.contriRect.bottom - 
Scroll[1]^^.contrlRect.top) < SBarMinLen then 
begin (not enough room, make invisible) 
EraseRectCScroll[ 1]^^.contrRect2; 
Scroll[1]^^.contrlVis := invisible; 
end 
else (enough room, make visible) 
Scrollt1]^^.contrlVis := visible; 


if EditText © nil then (fix TE rectangles) 
begin 
FixTextRects; 
EraseRectCMyW indow^ .portRect); 
InvalRectCMyWindow^ .portRect); 
end; 
end; ( of FixScrollbarRects) 


procedure UpdateOtherPane; {invalidate non active pane) 
var 
tempRect: array[1..2) of rect; 
delta: arrau[1..2) of integer; 
i, index: integer; 
pane: rect; 
intersect: boolean; 
begin 
case activePane of (get non active pane) 
I 
index := 2; 
2: 
index := 1; 
end; 


for i := 1 to 2 do (normalize viewRects) 
begin 
delta[i] := destRect[i].top; 
tempRect[i] := viewRect[i]; 
жы 0, -delta[i]); 
end; 


intersect := SectRect(tempRect[1), tempRect[2], pane); 
(get intersection) 


OffsetRect(pane, 0, deltalindex]); (place intersection pt) 


if intersect then (invalidate intersecting rectangle) 
InvalRect(pane); 
end; (of UpdateOtherPane) 


end. 
Listing: Test_Window.pas 
unit Test Window; 


(File name: Test. Window.Pas) 
(Function: Handle a Window) 


interface 
uses 
MuGlobals, MuScroll; 


procedure Close_Test_Window (whichWindow: WindowPtr); 
(Close our window) 

procedure Open_Test_Window; (Open our window ) 

procedure Update_Test_Window; (Update our window ) 
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procedure Do_Test_Window (muEvent: EventRecord); 
(Handle action to our window, like controls) 


inplementation 


procedure Close.Test Window; (Close our window) 
begin 
1f (MyWindow © nil) and (MyWindow = whichWindow) then 
begin 
DisposeWindow(MyWindow); (Clear window and controls) 
MyWindow := nil; 
TEDispose(EditText); (dispose of TE record) 
EditText := nil; 
end; (End for if KMyWindowOoni12)) 
end; (of Close Test Window) 


procedure UpDate. Test Window; (Update our window) 
begin 
PenNormal ; 
EraseRect(paneRect); (redraw dividing lines two panes ) 
SetRect(paneRect, Ø, Split^^.contrlValue + 1, 
Split^^.contrlRect.left, Split^^.contrlValue + 5); 
if ((Split^^.contrlValue > Ø) and (Split^^.contrlValue < 
Split^^.contrlMax)) then (is there enough room?) 
begin 
FrameRectCpaneRect); 
end, 


if (EditText © nil) then (update EditText to both panes) 
begin 
TEDeact ivateCEditText); 
SetEditTextC1); 
TEUpdateCMyWindow^.portRect, EditText); (Lower pane) 
SetEditText(2); 
TEUpdateCMyWindow^.portRect, EditText); (Upper pane) 
SetEditTextCactivePane); 
TEActivateCEditText); 
end; 


DrawControlsCMyWindow); 
DrewGrowIconCMyWindow); 
end; (of Update Test Window) 


(Draw all the controls) 
(Draw the Grow box) 


procedure Open Test Window; (Open our window and draw) 
var 
sTemp: str255; ( For initializing the text window) 
begin 
if (MyWindow = nil) then 
begin 
MyWindow := GetNewWindow(WindowID, nil, Pointer(-1)); 
SelectWindow(MyWindow); (Bring our window to front) 
SetPor tCMyWindow); 


( Make а scroll bars) 
Scro11[2] := GetNewControl(Scrollbar2, MyWindow); 
Scroll[1] := GetNewControl(Scrollbari, MyWindow); 
( Make a splitbar) 
Split := GetNewControl(Splitbar, MyWindow); 


(Set max/min and initial values of scrollbars) 

SetCt]Max(Scrol1[1], 0); 

SetCtlMinCScrolll1], 0); 

SetCtlValueCScroll(i], 0); 

SetCtlMaxCScrollI2], 0); 

SetCtlMinCScrollI2], 0); 

SetCtlValueCScrol1[2], 0); 

FixScrollbarRects; (redraw scroll/split bars done) 


FixTextRects; (get TE record’s rects for switching) 
activePane := 1; (Set active pane) 


EditText := TENew(viewRect[1], destRect[ 112; 
HLockCHandleCEditText2); ( setup attributes of TE ) 
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with EditText^^ do 
begin 
txFont := applFont; 
fontAscent := 12; 
lineHeight := 12* 3 + 1; 
end; 
HUnLock(Handle(EditText)); 
sTemp := “Splitbar available for those with split 
personalities’; 
TESetTextCPointerCOrd4CésTemp) + 1), length(sTemp), 
EditText); 
FixTextRects; 
TEActivateCEditText); 
ShowWindowCMyWindow); 
UpDate. Test. Window; 
end 
else 
SelectWindowCMyWindow); 
end; (of Open Test Window) 


(Do update to draw rest) 
(Already open, so show it) 


procedure HandleScrollBars CtheControl: ControlHandle; 
thePart: integer); (scroll Text while in scrollbar) 
var 
oldValue, delta, pane: integer; 
begin 
case GetCRefCon(theControl) of (find which pane) 
ScrollBar 1: 
pane := 1; 
ScrollBar2: 
pane := 2; 
end; 


case thePart of (get delta) 
inUpButton: 
delta := -1; 
inDownButton: 
delta := 1; 
inPageUp: 
delta := -(viewRect(pane].bottom - 
viewRect[panel.top) div EditText^^.lineHeight; 
inPageDown: 
delta := (viewRect[pane].bottom - viewRect[pane]l.top) 
div EditText^^.lineHeight; 
end; 


if thePart © Ø then (set Control” value & adjust text) 
begin 
oldValue := GetCtlValue(theControl); 
SetCtlValue(theControl, oldValue + delta); 
AdjustText(pane); 
end; 
end; (of HandleScrollBars) 


procedure Do_Test_Window; (Handle action to our window) 
var 

RefCon: integer; 
code: integer; {Location of event in window or controls) 
theValue: integer; (Current value of a control) 
whichWindow: WindowPtr ; 
myPt: Point; (Point where event happened) 
theControl: ControlHandle; (Handle for a control) 
extend: boolean; (TE extending with Shift key modifier} 


procedure Оо-А 5сго11Ваг (code: integer); (do ScrollBar} 
begin 
RefCon := GetCRefCon(theControl); (get control refcon) 
case RefCon of (Select correct scrollbar} 
Splitbar: (Splitbar) 
begin (start for this scroll bar) 
TEDeactivate(EditText); 
code := TrackControlCtheControl, myPt, nil); 
FixScrollbarRects; 
TEActivateCEditText); 
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end; 


Scrollbar 1: 
begin (start for this scroll bar) 
if code <> inThumb then 
code := TrackControlCtheControl, myPt, @Han- 
dleScrollBars) 


else 
begin 
code := TrackControl(theControl, myPt, nil); 
AdjustText(1); 
end; 
end; 
Scrollbar2: 
begin (start for this scroll bar) 


if code © inThumb then 


code :- TrackControl(theControl, myPt, @Han- 
dleScrollBars) 


else 
begin 
code :- TreckControlCtheControl, myPt, nil); 
AdjustText(2); 
end; 
end; 
end; (end of case) 
end; (Handle a ScrollBar being pressed) 
begin (Start of Window handler) 
if (MuWindow O nil) then 
begin 


code := FindWindow(muEvent.where, whichWindow); 


if (myEvent.what = MouseDown) and (MuWindow = 
whichWindow) then ( convert coords ) 


begin 
myPt := muEvent.where; 
GlobalToLocal(myPt); 
end; 


if (MyWindow = whichWindow) and (code = inContent) 
then (for our window) 
begin 
TEDeactivateCEditText); (remove hilighting) 
if PtInRect(MyPt, viewRect[ 11) then 
(determine which pane mouse down in) 
begin 
SetEditTextC1); 
activePane := 1; 
end 
else if PtInRect(MyPt, viewRect[2]) then 
begin 
SetEditText(2); 
activePane := 2; 


end; 
TEActivateCEditText); (put highlighting back) 


if PtInRect(MyPt, EditText**.viewRect) then 
begin 
extend := (BitAnd(mgEvent .modifiers, 
shiftKey) € 0); 
TEClickCmyPt, extend, EditText); 
end; 


code := FindControl(myPt, whichWindow, theCon- 
trol); (Get type of control) 
if (code © Ø) then (Check type of control) 
code := TrackControlCtheControl, myPt, nil); 


if (code = inUpButton) or (code = inDownButton) 
or (code = inThumb) or (code = inPageDown) or (code = 
inPageUp) then 


Do_A_Scrol 1Bar(code); (Do scrollbars} 
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end; €nd of procedure} 


end. (End of unit) 
Listing: SplitbarTest.pas 


program SplitbarTest; 

(Program name:SplitbarTest.Pas ) 

(Function: demo application of the Splitbar CDEF 17) 
(Historu: 3/14/89 Original bu Prototuper. 

(Modified to work right: Bu Kirk Chase ) 


uses 
Test Window, MyGlobals, MuScroll; 


var 
myEvent: EventRecord; (Event record for all events) 
doneFlag: boolean; (Exit program flag) 
code: integer; (Determine event type) 
SavePort, whichWindow: WindowPtr; 
tempRect, GrowRect, DragRect: Rect; (Rect for dragging) 
mResult: longint; (Menu list and item selected values) 
theMenu, theItem: integer; (Menu list and item selected) 
chCode: integer; (Key code) 
ch: char; (Key pressed in Ascii) 
IBeam: CursHandle; (IBeam Cursor) 
Sleep: integer; (MF sleep period) 
DoIt: boolean; 
ResumePeek: WindowPeek; 
sysResult: boolean; 


procedure D.About; (puts up About Box) 
var 
GetSelection: DialogPtr; 
ItemHit: integer; 
ExitDialog: boolean; 


begin 
GetSelection := GetNewDialog(AboutDialogID, nil, Pointer(- 


(Name of dialog) 


(Flag used to exit the Dialog) 


1)); (Bring in the dialog resource) 


ShowWindow(GetSelection); 
SelectWindow(GetSelection); 
SetPort(GetSelection); 
ExitDialog := FALSE; 
repeat 
ModalDialog(nil, itemHit); (Wait until an item is hit) 
if CItemHit = About. OK) then 
begin 
ExitDialog := TRUE; 
end; 
until ExitDialog; 
DisposDialog(GetSelection); 
end; (of D About) 


procedure Init Му Menus; 
begin 
CleerMenuBer ; 


(Initialize the menus) 
(Clear any old menu bars) 


AppleMenuHandle := GetMenu(CAppleMenuID); 
AddResMenuCAppleMenuHandle, ‘DRVR’); (Add in DAs) 
InsertMenuCAppleMenuHandle, 2); 

FileMenuHandle := GetMenu(F ileMenuID?; 
InsertMenu(CF i leMenuHandle, 0); 

EditMenuHandle := GetMenu(CEditMenuID); 
InsertMenuCEditMenuHandle, 0); 


DrawMenuBar ; 


(Draw the menu bar) 
end; (of Init My Menus) 


procedure FixMenus; (adjust menu items ) 
begin 
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1f (FrontWindow © nil) then (is there а front window?) 
begin 
if (FrontWindow € MyWindow) then (window mine?) 
begin (somebody else's window is in front) 
DisableItemCFileMenuHandle, C New); 
DisableItemCFileMenuHandle, C Close); 
EnableItemCEditMenuHandle, C_Cut); 
EnableI temCEditMenuHandle, C Copy); 
EnableItemCEditMenuHandle, C Paste); 
end 
else (ny window is up in front) 
begin 
EnableI tem(FileMenuHandle, C. Close); 
DisebleItemCFileMenuHandle, C New); 


DisableItemCEdi tMenuHandle, C_Undo); 


if (EditText^^.selStart © EditText**.selEnd) 
then (is there an non empty selection?) 
begin (non empty selection) 
EnableItemCEditMenuHandle, C_Cut); 
EnableItemCEditMenuHandle, C Copy); 
end 
else 
begin 
DisebleItemCEditMenuHandle, C_Cut); 
DisableI temCEditMenuHandle, C_Copy); 
end; 


if (TEGetScrapLen € 0) then (some TE Scrap?) 
EnableItemCEditMenuHandle, C_Paste) 
else 
DisableI temCEditMenuHandle, C_Paste); 
end; 
end 
else 
begin (no front window} 
DisebleItemCEditMenuHandle, C_Cut); 
DisableI temCEditMenuHandle, C Copy); 
DisebleItemCEditMenuHandle, C Paste); 
DisableItemCFileMenuHandle, C Close); 
EnableItemCFileMenuHandle, C.New); 


end; 
end; (of FixMenus) 


procedure FixCursor; (Non MF Cursor edjust) 
var 
mousept: Point; 
ContentRect: Rect; 


begin 
1f FrontWindow = nil then 
InitCursor 
else if FrontWindow = MyWindow then 
begin 


GetMouse(mousept ); 
ContentRect := MyWindow*.portRect; 
ContentRect.right := Split**.contrlRect. left; 


ContentRect bottom := ContentRect.bottom - SBarWidth; 


if (PtInRectCmousePt, ContentRect)) then 
SetCursor ( IBeam*~* ) 

else 
InitCursor ; 


end; 
end; (of FixCursor) 


procedure Handle My Menu (var doneFlag: boolean; theMenu, 
theltem: integer); (Handle menu selections) 
var 
DNA: integer; 
BoolHolder: boolean; 
DAName: Str255; 
SavePort: GrafPtr; 


begin (Start of procedure) 
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case theMenu of (Do selected menu list) 


AppleMenuID: 
begin 
case theItem of (Handle all commands in menu) 
About. Splitbar: 
begin 
D_About; (Call a dialog for About) 
end; 
otherwise (Handle the DAs) 
begin (Start of Otherwise) 
GetPort(SavePort); (Save current port) 


GetItemCAppleMenuHandle, theItem, DAName); 
DNA :- OpenDeskAcc(DAName ); 
SetPort(SavePort); 
end; 
end; €nd of item case) 
end; (End for this list} 


FileMenuID: 
begin 
case theltem of 
C_New: 
begin 
Open_Test_Window; 
end; 
C_Close: 
begin 
Close_Test_Window(MyW indow); 
end; 
C_Quit: 
begin 
doneFlag := TRUE; 
end; 
end; (End of item case) 
end; (End for this list) 


EditMenuID: 
begin 
BoolHolder := SystemEditCtheItem - 1); (Do DA ) 
if not (BoolHolder) then (If not DA get it) 
begin 
case theItem of 
C- Undo: 
begin 
end; 
C Cut: 
begin 
ScrollToSelection; 
TECutCEditText); (а Cut in a TE area) 
AdjustScrollBars; 
AdjustTextC 1); 
AdjustText(2); 
UpdateOtherPane ; 
ScrollToSelection; 
end; 
C- Copy: 
begin 
ScrollToSelection; 
TECopy(EditText); (a Copy in a TE area) 
UpdateOtherPane; 
ScrollToSelection; 
end; 
C_Paste: 
begin 
ScrollToSelection; 
TEPaste(EditText); (a Paste in a TE area) 
AdjustScrol1Bars; 
AdjustText( 1), 
AdjustText (2); 
UpdateOtherPane; 
ScrollToSelection; 
end; 
end; End of item case) 
end; 
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end; (End for this list) 
end; (End for lists) 


HiliteMenu(0); (Turn menu selection off) 
end; (of Handle М) Menu) 


procedure InitMac; (Initialize Mac Stuff) 
var 
MPtr: ^integer; 
begin 
MoreMasters; 
InitGraf CéthePort); 
InitFonts; 
InitWindows; 
InitMenus; 
TEInit; 
InitDialogs(ni1); 
FlushEventsCeveryEvent, 0); 
InitCursor; 


MPtr := pointerCmbarHe ightGlobal ); 
mBarHeight := MPtr^; 
end; (of InitMac) 


procedure InitApp; (Initialize Application Stuff) 
begin 
doneFlag := FALSE; (Do not exit program yet) 
InitMyMenus; {Initialize menu Баг) 
1Веат := GetCursor(IBeamCursor); (Get IBeam Cursor) 


DragRect := screenbits.bounds; (set drag rect) 
InsetRect(DragRect, 10, 10); 
DragRect.top := DragRect.top + mBarHeight; 


theErr := SusEnvirons(1, theWorld); 

1f (theWorld.machineTupe >= 0) and 
(NGetTrapAddress(WNETrapNum, ToolTrap) = 
NGetTrepAddressCUnImplTrepNum, ToolTrap)) then 


WNE := false 
else 

WNE := true; 
sleep := 10; 


if TEFromScrep © noErr then (get TE Scrap from Scrap) 
TESetScrapLen(0); 


EditText := nil; (Init EditText TE Record) 
MyWindow := nil; (Initialize the window) 
end; (of InitApp) 


InitApp; 
Open.Test Window; (Open the window routines ) 
repeet (Start of main event loop) 
FixCursor; 
FixMenus; 


if (EditText © nil) then (See if a TE is active) 


TEIdleCEditText); (Blink the cursor if everything is ok) 


if WNE then 


DoIt := WaitNextEventCeveryEvent, myEvent, sleep, nil) 


else 
begin 
Sys temTask ; 
DoIt := GetNextEventCeveryEvent, myEvent); 


end; 
if DoIt then (If event then...) 


begin (Start handling the event} 
code := FindWindow(mgEvent where, whichWindow); 
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case nyEvent.what of (Decide type of event) 


MouseDown: (Mouse button pressed) 
begin 
if (code = inMenuBar) then 
begin 
mResult := MenuSelect(myEvent .Where); 


theMenu := HiWord(mResult); 
theItem := LoWord(mResult); 
Handle My.MenuCdoneF lag, theMenu, 
theItem); (Handle the menu) 
end; (of inMenuBer) 


1f (code = InDrag) then 
begin 
DragWindow(whichWindow, myEvent.where, 
DragRect); (Drag the window) 
end; (of InDrag) 


1f (code = inGrow) then 
begin (Handle the growing) 
EraseRectCSplit^^.contrlRect?; 


SetRect(GrowRect, 55, 55 + 
Split^^.contrlValue, 1000, 1000); 

mResult := GrowWindow(whichWindow, 
myEvent.where, GrowRect); (Grow it) 

SizeWindowCwhichWindow, LoWord(mResult), 
HiWord(mResult), TRUE); (Resize to result) 

FixScrollbarRects; 

DrewGrowIconCwhichWindow); 

AdjustScrollBars; 

DrewControlsCMyWindow); 

AdjustTextC 1); 

AdjustText(2); 

ScrollToSelection; 

end; (of doing the growing) 


if (code = inGoAway) then 
begin 
if TrackGoAwayCwhichWindow, myEvent where) 
then (See if mouse released in GoAwau box) 
begin 
Close Test. WindowCMyWindow); 


end; 
end; (of InGoAway) 


1f (code = inContent) then 
begin 
f (whichWindow € FrontWindow) then 
SelectWindowCwhichWindow) 
else 
begin 
SetPor tCwhichWindow); 
Do_Test_WindowCmyEvent); 
end; (End of else) 
end; (End of inContent) 


1f (code = inSysWindow) then 
SustemClick(muEvent, whichWindow); 
end; (of MouseDown) 


KeyDown, AutoKey: (Handle key inputs) 
begin 
with myevent do 
begin 

chCode := BitAnd(message, CharCodeMask ); 

ch := CHR(chCode); (Change to ASCII} 

1f COdd(modif iers div CmdKey)) then 

begin 

mResult := MenuKeyCch); 
theMenu := HiWord(mResult); 
theItem := LoWord(mResult?; 
if (theMenu © 0) then 


363 


Handle_Mu_Menu(doneFlag, theMenu, 
theltem); (Do the menu selection) 


end 
else if (EditText O nil) then 

begin 
TEDeactivateCEditText); 
TEKeyCch, EditText); 
TEActivateCEditText); 
ScrollToSelection; 
UpdateOtherPane; 

end; 

end; (End for with) 
end; (of KeuDown,AutoKeu) 


UpDateEvt: 
begin 
whichWindow := WindowPtr(myEvent .message); 
1f whichWindow = MyWindow then 
begin 
GetPort(SavePort); (Save current port) 
SetPort(MyWindow); (Set port to my window) 
BeginUpdateCwhichWindow); 
Update_Test_Window; (Update this window) 
EndUpdate(whichWindow); 
SetPor t(SavePort); 


(Update event for a window) 


end; 
end; (of UpDateEvt) 


ActivateEvt: (Window activated event) 
begin {Handle the activation) 
whichWindow := WindowPtr(myevent .nessage?); 
1f odd(myEvent . modif iers) then 
SelectWindow(whichWindow); 
end; (of ActiveteEvt) 


MultiEvt: 
begin 
if Odd(myEvent . message? then 
begin (resume event) 
if FrontWindow = MyWindow then 
begin 
SetPor t CMyW indow); 
InvalRectCMyW indow^ .portRect); 
FixMenus; 
end 
else if FrontWindow O ni! then 
begin 
ResumePeek := WindowPeek(FrontWindow); 
if ResumePeek* .windowKind < Ø then 
begin 
myEvent what := activateEvt; 
BitSetC@myEvent modifiers, bit); 
sysResult := 
SystemEvent(myEvent); 
end; 
end; 
end (of resume event) 


else (suspend event) 


begin 
1f FrontWindow = MyWindow then 
begin 
Se tPor t CMyW indow); 


InvalRect(MuWindow .portRect); 
EnableI temCEditMenuHandle, C Undo); 
Епаб1е І temCEditMenuHandle, C_Cut); 
EnebleItemCEditMenuHandle, C Copy); 
EnebleItemCEditMenuHandle, C Paste); 
DrawGrowIconCMyWindow); 

end 

else if FrontWindow © nil then 

begin 

ResumePeek :- 
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WindowPeekCFrontWindow); 
1f ResumePeek* .windowK ind < 0 then 
begin 
myEvent.what := activateEvt; 
BitCirC@myEvent modifiers, 0110); 


sysResult := 
SystemEvent(myEvent); 
end; 
end; 
end; 
end; (of MultiEvt) 
end; (End of case) 
end; (end of GetNextEvent) 
until doneF lag; (End of the event loop) 
end. (End of the progrem) 
Listing: SplitbarTest.r 


XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKXXXK1XXXKXKXKXXKXXXEX 


* RMaker resource file sources. 
* File: SplitbarTest.R 
ЖЖЖ estes tse SS SSeS SSeS SS SESS SSSSSSOSSSSOSSS CSS SCS OT TCT TT TT 


SplitbarTest.RSRC 
19999999 


INCLUDE ХР“ 40:15Р 2.0:splitbar f:Splitbar Icon 
INCLUDE ХР“ 40:15Р 2.8:splitbar f:Splitbar.CDEF 17 


Type KCSB = STR 
Ü 
6 1989 by Kirk Chase and MacTutor\@Dversion 1.0 March 1989 


Type SIZE = GNRL 
езі 

.H 
4800 
L 
128000 
.L 
80000 
.I 


Type BNDL 
, 128 

KCSB 0 
ICN8 

0 128 
FREF 

0 128 


Type FREF 
, 128 
APPL 0 


Type DLOG 
x 


;1 
About 
50 120 189 389 
Visible NoGoAwau 
1 
1 
1 


* This is the DIALOG or ALERT item list. 
£ 

Type DITL 

x 


© The Best of MacTutor, Vol. 5 


‚1 
3 


Button Enabled 
86 83 112 163 
OK 


StaticText 
51 24 68 241 
@ 1989 Kirk Chase and MacTutor 


StaticText 
26 37 43 218 
Splitbar Test by Kirk Chase 


Type WIND 
x 


‚2 
Test Window 
41 3 338 508 
InVisible GoAway 
0 
2 


Type CNTL 
* 


, 10 
SplitBar 
@ 490 282 506 
Visible 
274 
10 
0 276 0 


‚9 
Scrollbar2 
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0 490 @ 506 
Visible 

16 

9 

1 100 1 


‚8 
Scrollbar 1 
6 490 282 506 
Visible 
16 
8 
1 100 1 


Type MENU 
* 


41 
\14 


About Splitbar... 
(- 


Quit/Q 
29 

Edit 

(Undo/Z 


Copy/C 
Paste/V 


J , APPLE menu title 
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Programmer 8 Workshop 
Spray Can and Paint Bucket Tools 


[Kevin Parichan is a senior, computer science major attend- 
ing Cal Poly in San Luis Obispo. He has been programming on 
the Mac since early 1985 when he got his first computer, the 
128K Mac. Right now he is doing some work using 4th 
Dimension.] 


Painting Tools 

When the Macintosh was first introduced, along with it came 
MacPaint and all those nifty painting tools that first awed us. 

I’m the kind of person who likes to take things apart, see how 
they work, and see if I can figure them out. So it has been with 
MacPaint's tools. 

We can all certainly create cheap imitation tools that expand 
ovals and rectangles that flash every time we move them. And 
since there are other, and far superior, painting programs around 
these days, certainly other people have figured out the mysteries 
of MacPaint. But I wanted to figure them out for myself. 

Ithought what better way than to create a Pascal unit thatcan 
be used by anybody whose program's purpose does not empha- 
size graphics, but would still like to supply the standard tools to 
their users. 

Since completing this unit (right now only in a Turbo Pascal 
version, and available on GEnie) I thought that I might share 
some of my knowledge with the rest of the people out there who 
are still scratching their heads. 

Of course, I won't show you everything. That would be too 
easy. I'll just show you how you can create both the Spray Can 
and Paint Bucket tools using some simple logic and those new 
Quickdraw routines that surfaced with the MacPlus. 


Along the way | did get some help 

Technical Note #163 gives a very short code fragment on 
how to do a color fill routine. The problem is that SeedCFill and 
SeedFill want different parameters. Plus, SeedCFill uses Color 
Quickdraw which of course doesn't much help those of us who 
can't afford a Mac II. 

You may also notice the function, NewBitMap. I've been 
using this since I first saw it in Scott Boyd's article on animated 
bitmaps. It's a handy little function. 

I've tried to set up the routines as independent from the 
program as possible and to do this I use the current grafport to 
pass information to the routines. For both tools we use the 
portBits, portRect, and pnPat fields. 

SeedFill and CopyMask were added when the MacPlus was 
introduced. They are both described in Inside Mac Vol.IV. Both 
are routines that operate on a portion of a bitmap, but I'll be using 
them on whole bitmaps which has yet to cause any problems. The 
spray can tool uses only CopyMask, so let's start with that. 
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The Spray Can 
PROCEDURE CopyMask (srcBits, maskBits, dstBits: 
srcRect, maskRect, dstRect: Rect); 


BitMap; 


As Inside Mac states: “.. . it transfers a bit image from the 
source bitmap to the destination bitmap only where the corre- 
sponding bit of the mask rectangle is a 1.” As you can see in the 
example below. 


Source Mask 


Figure 1 


Destination 


5 


So for the spray can tool what we’re going to do is create а 
source bitmap that contains the pattern we want to spray with, and 
a mask bitmap which has 1’s corresponding to where we want to 
paint. In our case, a spray pattern. 

In both examples, it's the call to Copy Mask which is used to 
apply a pattern. 

First thing we need to do is get the information we need from 
the current grafport. 


GetPortCworkPort); 

workBits:= workPort^.portBits; 
workRect:= workPort^.portRect; 
workPat:= workPort^.pnPat; 


Then set up the mask bitmap representing an exact duplicate 
of the spray can cursor, and also the source bitmap which is filled 
with the pattern we want to spray with. 

You may notice that the source bitmap is the same size as the 
area we are spraying into. That is because we want a continuous 
pattern throughout the window. If we used a smaller area, then 
the pattern from one spraying to the next would overlap and give 
us garbage on the screen. Also, the bounds for SprayBits is 17 
pixels on edge, while a cursor is 16 pixels on edge. That has to 
do with the way QuickDraw defines rectangles. I don't under- 
stand it fully, but I do know that changing the 16's into 15's 
bombs the program when you use the spray can. 

As everybody does when they get a new piece of code: 
experiment with it. 


GetIndStringCtheStr, 128, 1); 
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SetRect(tempRect,0,0,16,16); 

if NewBitMap(SprauBits,tempRect) = nil then Exit; 

StuffHex(SprauBits.baseAddr,theStr); 

if NewBitMap(PatBits,workRect) = nil then begin 
DisposPtr(SprauBits.baseAddr); 
Exit; 

end; 

SetPortBits(PatBits); 

FillRect(workRect,workPat); 


SetPortBits(workBits); 


Next is the main loop. The tickcount is used to slow down 
the motion so that too much isn’t sprayed at one time. Slowing 
down too much makes the spraying drag behind your mouse 
movements. 


repeat 

GetMouse(where); 

with where do 

SetRectCtempRect,h-8, v-8, h+8,v+8); 

tickValue:= TickCount + 1; 

repeat until CtickValue <= TickCount); 

CopyMask(PatBits, SprayBits, workBits, tempRect, 
sprayBits.bounds, tempRect); 

tickValue:= TickCount; 

repeat until CtickValue <= TickCount); 


until NOT Button; 


That’s all there is to the spray can, so now onto the... 


| The Paint Bucket 
For the paint bucket we also need to use SeedFill. 


PROCEDURE SeedFill (srcPtr, desPtr: Ptr; srcRow, dstRow, 
height, words, seedH, seedV: Integer); 


As Inside Mac state, “ . . . computes a destination bit image 
with 1’s only in the pixels where paint can leak from the starting 
seed point...” All we need to do then after calling SeedFill is 
apply a pattern to the destination bit image which can be accom- 
plished with CopyMask 

SeedFill uses pointers pointing into bitmaps. It’s easier just 
to copy the working image to a new bitmap and set the pointers 
to its baseAddr and it helps in other ways as explained below. 
Besides, windows usually only show a view of a much larger 
image. If SeedFill is to work on a whole image you would use the 
larger image’s baseAddr anyway. But if you really know what 
you're doing and only want to fill a portion of the bitmap, then 
I’m afraid you’re going to have to do some pointer arithmetic. 

Get the same information as before. 


GetPortCworkPort); 
workBits:= workPort^.portBits; 
workRect:= workPort^.portRect; 


workPat:= workPort^.pnPat; 


Set up our two bitmaps for the calls to SeedFill and 
CopyMask. Make a copy of the image we are using the paint 
bucket on, which gets our addresses right and also helps us 
because the current grafport is a window and its bitmap also 
contains the title bar. You can also see where this code needs 
modification. What about scroll bars and and the grow icon. A 
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simple fix is to pass to the routines the area you want to fill or 
spray in. Don’t think clipping the area will work. SeedFill is not 
clipped to the current grafport. Take out the code that makes a 
copy of the work image and see for yourself. 


if NewBitMapCdstMap, workRect ) 

if NewBitMapCsrcMap, workRect) 
DisposPtr(CdstMap .baseAddr ); 
Exit; 

end; 

CopyBitsCworkBi ts, srcMap, workRect, workRect, srcCopy,ni 12; 


nil then Exit; 
nil then begin 


Now we check to see if we are filling on a black pixel. To 
act just like a normal paint bucket we need to apply the pattern to 
the black areas instead of the white. But SeedFill only works on 
white, so we invert the image before and after calling SeedFill. 


onBlack:= GetPixel(where.h,where у), 

if onBlack then begin 
SetPortBits(srcMap); 
InvertRect(workRect); 
SetPortBits(workBits); 


end; 


Setup the bitmap containing the pattern we want to fill with. 
Don't forget to invert the pattern as well if we are starting the fill 
on a black pixel. 


if NewBitMapCPatBits,workRect) = nil then begin 
DisposPtr(CdstMap .baseAddr ); 
DisposPtr(srcMap .baseAddr 2; 
Exit; 
end; 
SetPortBits(PatBits); 
FillRectCworkRect , workPat); 
if onBlack then InvertRect(workRect); 


SetPortBits(workBits); 


This is the area that I don't want to be bothered with. I just 
say that I'm attempting to fill the entire bitmap. Don't forget to 
make words an even number. Height is the height of our image 
in pixels and words is the width of our image in words (as in 2 
bytes). 


srcPtr:= srcMap.baseAddr; 
srcRow:= srcMap .rowBytes; 
dstPtr:= dstMap.baseAddr ; 
dstRow:= dstMap..rowBytes; 
height:= dstMap.bounds.bottom - dstMap.bounds. top; 


words:= (dstRow + 1) DIV 2; 


And here it is. The code that does all the real work. Simple, 
isn’t it. Where is the point where the mouse was clicked in the 
window in local coordinates. 


SeedF ill(srcPtr,dstPtr,srcRow,dstRow, height, words, where .h, where.v); 
CopyMask (PatBi ts, dstMap, srcMap, workRect, workRect, srcMap . bounds); 


We check to see if we started filling on a black pixel, and if 
SO, invert our image once again, then copybit it to the grafport. 


if onBlack then begin 
SetPor tBits(srcMap); 
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InvertRect(workRect); 
SetPortBits(workBits); 
end; 


CopuBits(srcMap,workBits,workRect,workRect,srcCopu,nil); 


Well, that’s it. Not much to it. There are some obvious 
places to improve upon, but like I said, I tried to make the code 
as generic as possible. It’s your job to customize it to suit your 
needs. 

Listing: ToolDeno.pas 
Program ToolDemo; 


($U- 
($R ToolDemoRes) 


SetRect(tempRect,0,0@,16,16); 
1f NewBitMap(SprayBits, tempRect) = nil then Exit; 
Stuf f HexCSprayB i ts .баѕеАдаг, theStr); 


1f NewBitMapCPatBits,workRect) = nil then begin 
DisposPtr(SprayBits.baseAddr ); 
Exit; 
end; 
Se tPortBits(PatBits); 
FillRect(workRect , workPat); 
SetPortBits(workBits); 


repeat 
GetMouse(where?; 
with where do 
SetRectCtempRect,h-8,v-8,h*8,v*8); 
tickValue:= TickCount + 1; 
repeat until CtickValue <= TickCount); 
CopyMask(PatBi ts, SprayBits, workBits, tempRect, SprajBits bounds, tempRect); 
tickValue:= TickCount; 
repeat until (tickValue <= TickCount); 


until NOT Button; 


DisposPtr(PatBits.baseAddr ); 
DisposPtr(SpragBits .baseAddr ); 


Uses 
MemTypes, QuickDraw, OSIntf , ToolIntf ; 
Const 
AppleMenu - 128; 
FileMenu = 129; 
EditMenu = 130; 
ToolMenu = 131; 
SprayItem = 1; 
BucketItem = 2; 
PatternMenu = 132; 
WhiteItem = 1; 
LtGreyItem = 2; 
GraylI tem = 3; 
DkGrayItem = 4; 
BlackItem = 5; 
Var 
myMenus : array [AppleMenu. .PatternMenu] of MenuHandle; 
nyWindow : WindowPtr; 
Finished : Boolean; 
GrowArea : Rect; 
CurrentPat : Integer; 
CurrentTool : Integer; 


(HE EHE HE ETEEEE HEEL ETHEEE E EET enc ex CET 83 snes 2 923 09 32 02 1023 82 2 92 2 EET 3 92 02 00309 2 92 os et E EE EE EEEE EHE E EE ELE GT) 
Function NewBitMap (VAR theBitMap : BitMap; theRect : Rect) : 
Ptr; 
Begin 
NewBitMap:= nil; 
with theBitMap, theRect do begin 
rowBytes:= (Cright-left+15) DIV 16) *2; 
baseAddr := NewPtr(rowBytes * Cbottom-top)); 
bounds:= theRect; 
1f MemError = noErr then 
NewBitMap:= baseAddr; 


End; 
Procedure DoPaintBucket (where : Point); 
Var 
workPort : GrafPtr; 
workBits : BitMap; 
workRect : Rect; 
workPat : Pattern; 
PatBits : BitMap; 
onBlack : Boolean; 
srcMap : BitMap; 
dstMap : BitMap; 
srcPtr : Ptr; 
dstPtr : Ptr; 
srcRow : Integer; 
ds tRow : Integer; 
height : Integer; 
words : Integer; 
Begin 
GetPor tCworkPor t); 
workBits:= workPort^.portBits; 


workRect:= workPort^.portRect; 
workPat:= workPort*.pnPat; 


1f NewBitMapCdstMap, workRect) 

14 NewBitMap(srcMap, workRect) 
DisposPtr(dstMap .baseAddr 2; 
Exit; 


nil then Exit; 
nil then begin 


end; 
CopyB i tsCworkBi ts, srcMap, workRect , workRect , srcCopy, ni 12; 


onBlack:= GetPixelCwhere.h,where.v); 

1f onBlack then begin 
SetPortBits(srcMap?); 
Inver tRect(workRect); 
SetPortBits(workBits); 

end; 


1f NewBitMap(PatBits, workRect) = nil then begin 
DisposPtr(dstMap .baseAddr ); 
DisposPtr(srcMap .baseAddr ); 
Exit; 


end; 

End; 

Procedure DoSprayCan (where : 

Var 
workPort : GrafPtr; 
workBits : BitMap; 
workRect : Rect; 
workPat : Pattern; 
theStr : Str255; 
tempRect : Rect; 
SprayBits : BitMap; 
PatBits : BitMap; 
tickValue : LongInt; 

Begin 
GetPort(workPort); 


workBits:= workPort^.portBits; 
workRect:= workPort^.portRect; 
workPat:= workPort^.pnPat; 


GetIndStringCtheStr, 128, 1); 
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end; 

SetPortBits(PatBits); 
FillRectCworkRect , workPat); 

if onBlack then InvertRectCworkRect); 
SetPortBits(workBits); 

srcPtr:= srcMap.baseAddr; 
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srcRow:= srcMap.rowButes; 


dstPtr:= dstMap.baseAddr ; 
dstRow:= dstMap.rowBytes; 
height:= dstMap.bounds.bottom - dstMap.bounds. top; 


words:= CdstRow + 1) DIV 2; 


SeedF i11¢srcPtr,dstP tr, srcRow, dstRow, height, words, where .h, where. v); 
CopyMask(PatBi ts, dstMap, srcMap, workRect, workRect, srcMap bounds); 


if onBlack then begin 
SetPor tBits(srcMap); 
Inver tRectCworkRect); 
setPor tBitsCworkBits); 
end; 
CopyBi tsCsrcMap, workBits, workRect, workRect, srcCopy,nil); 


DisposPtr(srcMap .baseAddr ); 

DisposPtr(dstMap .baseAddr ); 

DisposPtr(PatBits.baseAddr ); 
End; 


(ttti n n HHETHHHHHHIUHHTHH HH eae testes UH HH HUN HHHHHEIHHI) 
Procedure ProcessMenu (codeWord : LongInt); 


Var 
menuNum  : Integer; 
itemNum — : Integer; 
itemStr : Str255; 
dummy : Integer; 
Begin 


if codeWord © Ø then begin 
menuNum := HiWord(codeWord); 
itemNum := LoWordCcodeWord); 
case menuNum of 
AppleMenu : 
begin 
GetItem(myMenus LAppleMenu], i temNum, i temStr); 
dummy:= OpenDeskAcc(itemStr); 
end; 
FileMenu : Finished:= TRUE; 
EditMenu : 1f NOT SystemEditCitemNum - 1) then ; 
ToolMenu : 
begin 
CheckItemCmyMenus [Too Menu], CurrentTool, false); 
CurrentTool:= itemNum; 
Check I temCmyMenus [ToolMenul, CurrentTool, true); 
end; 
PatternMenu : 
begin 
Check temCmyMenus [Pat ternMenu], CurrentPat, false); 
CurrentPat:= itemNum; 
Check I temCmyMenus [Pat ternMenu], CurrentPat, true); 


se tPor t Стун indow); 
case CurrentPat of 
WhiteItem  : PenPat(white); 
LtGrayItem : PenPat(1tGrau); 
GrayI tem : PenPat(gray); 
DkGrayItem : PenPat(dkGrau); 
BlackItem : PenPat(black); 
end 
end; 
end; (case) 
HiliteMenu(0); 
end; (big 1f) 


End; 


(ttti tH HHHHHEHEHHHEHEHEHHHT ent ent tes enn aes sense aes ees tees een ett) 


Procedure DealWithMouseDownsCtheEvent: EventRecord); 
Var 


whichWindow : WindowPtr; 

mousel oc : Point; 

windowLoc : Integer; 

position : LongInt; 
Begin 


mouseLoc:= theEvent where; 
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windowLoc:= FindWindowC(mouseLoc, wh ichW indow); 
case windowLoc of 


inMenuBar : ProcessMenu(MenuSelect(mouseLoc)); 
inSysWindow : SystemClickCtheEvent,whichWindow); 
inDrag 


DragWindow(wh ichWindow,mouseLoc, screenB i ts bounds); 
inGoAway : If TrackGoAwayCwhichWindow, mouseLoc) then 
Finished:= true; 
inGrow : 
begin 
position:= GrowWindowCwhichWindow, mouseLoc,GrowArea); 
if position © Ø then begin 
SizeWindowCwhichw indow, loword(posi tion), hiword(position), false); 
SetPortCwhichWindow); 
InvalRect(whichWindow^ .portRect); 
end; 
end; 
inZoomIn, inZoomOut : 
begin 
if TrackBoxCwhichWindow,mouseLoc, windowLoc) then 
begin 
SetPortCwhichWindow?); 
ClipRect(whichWindow^ .portRect); 
EraseRect(whichWindow^ .portRect); 
ZoomW indowCwh ichWindow,w indowLoc, true); 
InvalRect(whichWindow^ .portRect); 
end; 
end; 
inContent : 
begin 
16 whichWindow o FrontWindow then 
SelectWindowCwhichWindow) 
else begin 
SetPor tCwhichWindow); 
Global ToLocal (mouseLoc); 
case CurrentTool of 


Sprayltem : DoSprayCan(mouseLoc); 
BucketItem : DoPaintBucket(mouseLoc); 
end; 
end; 
end; 
end; 


End; 


Ааны DealWithKeuDowns(theEvent: EventRecord); 
ar 
CharCode 
Begin 
CharCode:- CHR(BitAndCtheEvent .message, charCodeMask )); 
if BitAndCtheEvent modif iers, CmdKey) = CmdKey 
, then ProcessMenuCMenuKeyCCharCode 22; 
End; 


: char; 


Procedure DealWithActivates(theEvent: EventRecord); 
Var 

theWindow: WindowPtr; 
Begin 

theWindow := WindowPtr(theEvent . message); 

1f Odd(theEvent .modif iers) 

then SetPortCtheWindow); 

End; 


Procedure DealWithUpdates(theEvent: EventRecord); 
Var 
theWindow : WindowPtr; 
tempPort : WindowPtr; 
Begin 
theWindow := WindowPtrCtheEvent . message); 
GetPortCtempPort); 
SetPor tC theWindow); 
BeginUpDateCtheWindow); 
ClipRectCtheWindow^ .portRect); 
EraseRectCtheWindow^.portRect); 
PenSize(5,5); 
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FrameOval(theWindow .portRect); 
PenSize(1,1); 
EndUpDate(theWindow); 


SetPort(tempPort); 
End; 
Procedure MainEventLoop; 
Var 

Event : EventRecord; 
Begin 

repeat 

SystemTask; 


if GetNextEventCeveryEvent, Event) then 
case Event.what of 


mouseDown : DealWithMouseDowns(Event); 
AutoKey : DealWithKeyDowns(Event); 
KeyDown : DealWithKeyDowns(Event); 


ActivateEvt : DealWithActivates(CEvent); 
UpdateEvt : DealWithUpdates(Event); 
end; (case) 
until Finished; 
End; 


(1112 19 88 EEIEIEE sa LEISIS IEAI 2 182 0303 2 1023 89 2 02 1080209 12 sees eee 02 1102 09 12:12 2 gee 09 2 02 0001 EE sages tee HE soe os te HEEE ) 


Procedure SetupStuff ; 


index : Integer; 
Begin 

MaxApp1Zone; 
InitGraf (@thePor t); 
InitFonts; 
InitWindows; 
InitMenus; 

TEInit; 
InitDialogs(nil); 


for index:= AppleMenu to PatternMenu do begin 
myMenus[ index] := GetMenu( index); 
Inser tMenuCmyMenus [index], 8); 


end; 

AddResMenu(myMenus [AppleMenu], DRVR ); 
DrawMenuBar ; 

CurrentTool:= Spray! tem; 

CurrentPat:= BlackI tem; 

Check I tem(myMenus (Тоо Menu], CurrentTool, true); 
Check I tem(myMenus [Pat ternMenu],CurrentPat, true); 
myWindow:= GetNewWindow( 1000, nil ,pointer(- 122; 


Finished:= false; 
with screenBits.bounds do 
SetRect(GrowArea,150,150,right,bottom); 


FlushEvents(everuEvent,0); 
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InitCursor ; 
End; 


Begin 
SetupStuff ; 
MainEventLoop; 

End. 


Listing: ToolDemo.r 
ToolDemoRes 


Type MENU 
, 128 
\ 14 


, 129 
File 
Quit/Q 


, 130 
Edit 
Undo /Z 
(- 

Cut /X 
Copy/C 
Paste/V 
Clear 


, 131 

Tools 

Spray Can 
Paint Bucket 


, 132 
Patterns 
White/1 
Light Grau/2 
Gray/3 

Dark Gray/4 
Black/5 


Type STR® 
, 128 


1 
0 10000 102080040000228200 10480 10 104409008022208004 120000408000080 


Type WIND 

, 1000 

Tool Demo 

58 50 300 400 
Visible GoAway 
8 

0 
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Advanced Mac'ing 
List of Controls LDEF 


List-Of-Controls LDEF 
Introduction 
I recently needed to implement a list, in which each cell 
would be an active control. It turned out to be a little harder to do 
than I thought it would be. To save others the trouble, I thought 
I'd describe how I made it all work. 


Overview 

Iuse Apple'sList Manager to manipulate my list of controls. 
Each element of the list contains a ControlHandle to a PopUp- 
Menu control. Whenever a mouseDown event occurs in the list, 
Ifind out if itis one of the controls, and if so, call TrackControl() 
(IM v1 p323) to deal with it. If the mouseDown is in the list, but 
notinan active part of the control, I pass the event off to LClick() 
(IM v4 p273), so the Apple List Manager can handle it. 

Whenever the user selects or unselects a list element, or 
brings a new control into view by scrolling the list, the List 
Manager will send a message to the list's LDEF telling it to draw 
or hilite the list element. My LDEF will then set the control's 
hilite state as needed to assure that it is drawn properly, and then 
call Draw1Control() (IM v4 p53) to do the actual drawing. 

A routine called FixCtlRects() is called in the test program 
whenever a control may have changed position in the list's 
display, to make sure that its controlRect field matches its list 
rectangle, and that it won't be drawn if itis out of the list' s display 
area. 

The example program uses the PopUp-Menu control de- 
scribed in MacTutor, September 1988, PopUp-Menu Control 
CDEF. I could have used a different CDEF, but I would have had 
to include the CDEF's source code, and I didn’t want to make this 
article any longer than necessary. 


LDEFS 

LDEFs are described on pages 278-277 of Inside Mac, 
Volume Four, in the List Manager chapter (pages 259-282). The 
‘РЕР associated with a list is loaded into memory when the list 
is created. Like other. DEFs (MDEFs, CDEFs, etc.), the code 
resource hasa single entry pointat its first byte (i.e., it has no jump 
table). The entry point must be a procedure with the following 
definition: 


PROCEDURE MuLDEF( 
lMessage: INTEGER; 
lSelect: Boolean; 
lRect: Rect; 
1Cell: Cell; 
]Data0ffset, 
lDataLen: INTEGER; 


lHandle: ListHandle); 
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The function and argument names may be changed, of 
course, but their order and type must be as shown here (from IM 
v4 p276). 

Whenanew listis created using the LNew() function (IM v4 
p270), one of the parameters you must give to LNew0 is the 
resource ID of the LDEF you want the list to use. Apple's default 
LDEF has a resource ID of 0. Our LDEF has a resource ID of 
RES ID (128). When we create the new list, the List Manager 
will load the specified LDEF, and store a handle to it in the 
listDefProc field of the resulting list record. Whenever a cell of 
the list needs to be drawn or hilited, the List Manager will send 
a message to the LDEF, and the LDEF will do the work. 


LDEF Messages 

An LDEF message is just a procedure call to the LDEF's 
MyLDEF() routine, with IMessage (an integer) equal to a mean- 
ingful value. If the List Manager wants the LDEF to draw a cell, 
it calls MyLDEF() with IMessage equal to IDrawMsg (1). If the 
cell is to be hilited, MyLDEFY) is called with IMessage equal to 
IHiliteMsg (2). MyLDEF0 contains a CASE statement, keyed to 
the IMessage parameter's value. If IMessage equals IDrawMsg, 
the routine doDrawMsg() is called. If IMessage equals ІНІ- 
iteMsg, doHiliteMsg() is called. That's all there is to LDEF 
message passing. 

There are four different messages an LDEF may receive. 
Twoof them, IDrawMsg and lHiliteMsg, must be handled by all 
LDEFs. 

When the LDEF gets а IDrawMsg message, it needs to draw 
the given list cell. If the list cell is selected (ie., if ISelect is 
TRUE), then you need to hilite the cell, to tell the user that it’s 
been selected. The LDEF used in this article simply calls 
Draw 1Control() to draw the control stored in the given cell. First 
it has to diddle with the control’s rectangle, though, as we'll see 
later. 

The IHiliteMsg message is sent to the LDEF when a previ- 
ously drawn cell needs to be hilited or unhilited. In most cases, 
this is done by simply inverting the cell’s rectangle. Our LDEF 
has to get a little fancier. 

The other two LDEF messages, IInitMsg and ICloseMsg, 
need only be implemented by the LDEF if each list handled by the 
LDEF needs to be initialized in some way, and then have its 
initialization voided when the list is disposed of. In this LDEF, 
however, no such initialization or deinitialization need be done, 
SO it does nothing when it receives those messages. 


List Hilighting 
We need to be able to draw the control in such a way as to 


| make it look selected in the list. The mechanism for inverting the 
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control’s title already exists in the CDEF, so we'll use that to 
indicate that the control is selected in the list. 

The careful readers of the PopUp-Menu CDEF article and 
code may have noticed that a partCode was defined for the title 
of the pop-up menu (titlePart = 2), but that this partCode was 
never returned by doTestCntl(). The part code exists solely for 
this article. By setting the contrlHilite field of the control to be 
drawn to titlePart before calling Draw 1 Control(), we can guaran- 
tee that the control will have its title hilighted when it is drawn. 


The Example Program 

The example program is a very stripped Mac application. It 
simply initializes all of the usual managers, throws up a dialog, 
and cycles through ModalDialog() (IM v1 p415) until the user 
selects the dialog's OK button. Most of the work of handling the 
list and the controls it contains is done by the filterProc MyFil- 
ter() — the address of which is passed to ModalDialog() in the 
main program — and its helper functions, doMouseDown() and 
doKeyDown(). 

After the user clicks the OK button, the program exits the 
ModalDialog() loop, disposes of the controls, list, and dialog, 
and quits. The final values of the controls are not accessed, 
because I’m not actually doing anything with them. In a real 
program you’d get the final values out of the controls, using 
GetCtlMaxQ) and GetCtlMin() as described in PopUp-Menu 
Control CDEF. 


Using the List-Of-Controls LDEF 

The LDEF expects to finda control handle in each of its cells. 
We have to put these handles there ourselves. First we need to 
create the list itself, which we do with a call to LNew() in the 
routine InitList(). The only interesting part of this call is the use 
of RES ID (128, the resource ID of our LDEF), rather than zero 
(0), Apple's default LDEF. 

Next, we need to create the controls we wish to add to the list. 
This is accomplished with calls to NewControl() (IM v1 p319), 
in the routine ReadData(). I read the resource ID's of the controls 
I need from the ‘INT#’’ resource I’ ve placed in the resource fork, 
and then read in the associated “CNTL’ resources. 

I give the control arectangle that is out of sight. It gets drawn 
despite my saying that I want it to be invisible (very irritating), 
so I just hide it, so that it can’t be seen until I want it to be seen. 

After getting a control handle from NewControl(), the con- 
trol is made visible (but not drawn) by placing TRUE (255) in its 
contrlVis field. ShowControl() (IM v1 p322) would try to draw 
the control, but that's a waste of time, because the window is still 
invisible. 

Finally, the control handle is placed in a new cell in the list. 
From there, we can extract it, and pass it along to Draw1Control() 
and TrackControl() as necessary. 


Problems 
At first Ithought that I could just update a control's rectangle 
whenever the cell it was in received an IDrawMsg or an lHil- 
iteMsg. But that alone won't work, because the List Manager 
uses ScrollRect() (IM v1 p187) to scroll the bits inside the list's 


372 


rectangle, and only redraws cells as they come into view. This 
means that after the initial drawing of the list, the only place in 
which cells are redrawn is in the top cell frame or in the bottom 
cell frame. If you modify the control rectangle to match the cell 
rectangle only when the cell is redrawn, then sooner or later, all 
of the controls are going to have either the top or bottom cell 
frame as their rectangles. It may look like there are controls in the 
middle of the list, but those are just scrolled bit-images; the 
controls will think they are in the top and bottom frames. 

So, when you click in a control in the middle of the list, the 
control does not respond... because it's not really there. The 
thing you thought was a control was just a picture of a control. 
The control is in either the top or bottom cell frame (depending 
on where it was drawn last). If you click in the top or bottom cell 
frame, you'll click in a control, all right, but not necessarily the 
one you see there. Your click will get picked up by the first 
control in the window's control list (not the List Manager list) 
that was recently redrawn in that frame. Argh! 

Here comes the kludge. The only way the user can move the 
controls on the list is with the list's scroll bar. Therefore, 
whenever we receive a mouseDown event in the list that is not in 
one of our controls, we have to call FixCtlRects(). FixCtIRects0 
just walks through the list, getting each cell's rectangle and 
setting the rectangle of the control in the cell to match. If the cell 
is invisible, then control is made invisible, and vice versa. This 
doesn't take too long for a short list, but if you had a couple of 
hundred controls, it would be noticeably slow. 

We also have to call FixCtlRects() after reading in the 
controls the first time, to make sure they're displayed properly. 

It's a kludge, but it works, so what the hey. 


Miscellaneous Notes 

There are few other things about the LDEF, the pop-up menu 
CDEF, and its example program that are worth mentioning. 

Note that I pass POINTER(-1) to TrackControl() in do- 
MouseDown(). This enables the pop-up menu's CDEF's au- 
toTrack function. This is the function that pops up the PopUp- 
Menu via PopUpMenuSelect() (IM v5 p241), as described in 
detail in PopUp-Menu Control CDEF. 

CenterWindow( just centers a window in the screen, about 
two-thirds of the way up. 


| Acknowledgements 
I started this project in order to do something we needed to 
do at work, but it kind of took on a life of its own when I realized 
that there was an article in it. I'd like to thank the guys at Abacus 
— Dan, Jim, and Will — for letting me spend the time I did on 
this. It won't happen again... for another week or two, anyway. 


Listing: Test.make 


8 Test.make 
n 


Test ffTest.r ControlLDEF.LDEF PopMenuCDEF .CDEF 
Rez -rd Test.r -o Test 


Test ffTest.p.o д 
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ControlLDEF .LDEF д 
PopMenuCDEF . CDEF д 
Test.r 

Link д 
Test.p.o 
* (Libraries) "Runtime.o д 
* (Libraries)^Interface.o д 
“(PLibraries}*PasLib.o д 
-o Test 


ControllDEF.LDEF ff ControlLDEF.p.o 
Link -sg ControlLDEF д 
-rt LDEF=1 à 
-m MYLDEF ControlLDEF.p.o à 
* (Libreries) "Interface.o д 
-o ControllDEF.LDEF 


PopMenuCDEF.CDEF ff PopMenuCDEF.p.o 


Link -sg PopMenuCDEF д 
-rt CDEF=1 д 
-m MYCONTROL PopMenuCDEF.p.oà 
*(Libraries)*Interface.o д 
“(PLibraries)*PasLib.o д 


-o PopMenuCDEF . CDEF 


PopMenuCDEF .p.o f PopMenuCDEF .р PopMenuIntf .p 
Pascal PopMenuCDEF .p -o PopMenuCDEF .p.o 


Test.p.o f Test.p 
Pascal Test.p -o Test.p.o 


ControlLDEF.p.o f ControlLDEF.p PopMenuIntf .p 
Pascal ControlLDEF.p -o ControlLDEF.p.o 


8 END OF FILE: Test.make 
Listing: ControlLDEF .P 


(ЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖАЖХЖЖЖАЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


ControlLDEF.p: List Definition Function for list of controls. 


JOCODOOODOOOOOOOOOOOOOOODODOOOOOOOOOOOOIOODODODOOOOOOEIE) 
UNIT ControlLDEF ; 


INTERFACE 

USES 
($0 MenTypes.p 
($U QuickDraw.p 
($U OSIntf .p 
($U ToolIntf.p 
($U PackIntf .p 
($U PopMenuIntf .p 


) MemTypes, 
) QuickDrew, 
) OSIntf, 
) ToolIntf, 
) PackIntf, 
) PopMenuIntf ; 


PROCEDURE MyLDEFC Message: INTEGER; 1Select: Boolean; 


lRect: Кес; 1Се11: Cell; lData0ffset, IDataLen: INTEGER; 


lHandle: ListHandle); 


IMPLEMENTATION 
CONST 
isVIS = 255; 
notVIS = 0; 
TYPE 


StateStuff = record 
oldPen: PenState; 
oldPort: GrafPtr; 
oldClip: RgnHandle; 
newClip: RgnHandle; 

end; (StateStuff ) 


PROCEDURE DrawCellClSelect: Boolean;lRect: Rect; 
1Се11: Cell;lHandle: ListHandle);FORWARD; 


(ЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖ 
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MULDEF: List Definition Function for Controls list. 
Responds to LDrawMsg and lHiliteMsg; ignores 
lInitMsg and 1CloseMsg. 

МАМЫ 5522522 У 


PROCEDURE MyLDEFC Message: INTEGER; Select: Boolean; 
]Rect: Кесі;1Се11: Cell; 1Data0ffset, IDataLen: INTEGER; 


lHandle: ListHandle); 
BEGIN 
CASE 1Меѕѕаде ОҒ 
1InitMsg: 
; (по initialization needed ) 
1CloseMsg: 
; ( no deallocation needed) 


lDrawMsg, lHiliteMsg: 
DrawCellClSelect, lRect, 1Се11, lHandle); 
END; (cese) 
END; (MyLDEF ) 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


SaveState: Saves the current drawing environment. 
DOCOOCODODOODDOOOOOOOODOOOOOOOOOOOOOOOOOOROOOOOOOEOKOOOE) 


PROCEDURE SaveState(VAR oldState: StateStuff; 
lRect: Rect; Handle: ListHandle); 
BEGIN 


WITH oldState DO BEGIN 
( save the current pen state ) 
GetPenStateColdPen); 
( save current grafPort, set new grafPort ) 
GetPortColdPort); 
SetPortClHandle^*^ .рогі); 


( allocate space for old and new clipping regions ) 


oldClip := NewRgn; 
newClip := NewRgn; 
( save old clipping region ) 
GetClipColdClip); 
( set newClip region to given rectangle ) 
RectRgn(newClip, 1Rect); 
( intersection of rect and region ) 
SectRgnColdClip, newClip, newClip); 
( set grafPorts’ clip region to the intersection ) 
SetClip(newClip); 
END; (with ) 
END; ( SaveState ) 


(ЖЖЖЖЖЖЖХАЖХЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖХАЖЖЖЖЖЖЖЖЖЖЖЖЖХАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


RestoreState: Restores current drawing environment. 
ЖЖЖЖЖЖЖАЖЖАЖЖАЖЖЖЖЖЖАЖЖЖЖЖАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 


PROCEDURE RestoreStateColdState: StateStuff); 
BEGIN 
WITH oldState DO BEGIN 
( restore the previous clipping region ) 
SetClipColdClip); 
( restore the previous pen state ) 
SetPenStateColdPen); 
( restore the previous grafPort ) 
SetPortColdPort); 
( dispose of the regions” storage ) 
DisposeRgn(oldClip); 
DisposeRgn(newC1ip); 
END; ( with } 
END; ( RestoreState ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
DrawCell: Draws the given cell, either selected or 


normal, by drawing the control stored in the cell. 
FAI OOK ) 


PROCEDURE DrewCellClSelect: Boolean; 1Rect: Rect; 
1Cell: Cell; 1Напа1е: ListHandle); 
VAR 
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oldState: StateStuff; 
ch: Сопіго1Напд1е; 
d1: INTEGER; 


BEGIN 
( save the current drawing environment ) 
SaveState(oldState, IRect, lHandle); 


( get the cell’s data ) 
dl := sizeof (Handle); 
LGetCellCéch, dl, 1Се11, lHandle); 


( update the control’s fields ) 
with ch^^ do begin 
contriRect ]Rect; 
contrlVis isVIS; 


( ensure proper hiliting ) 
1f (T1Select) then 
contrlHilite := titlePart 
else begin 
contriHilite := Ø; 
end; ( if ) 
end; (with ch^^ ) 


( draw the control ) 
Draw iControlCch2; 


( restore the previous drawing state ) 
RestoreStateColdState); 

END; (OrewCell ) 

END. ( ControlLDEF) 

Listing: Test.p 


(YXXXXXXXXXXXXX1XXXXXXXXXXXXXXXXXXXXXXXXXXXKXXKXKXXXXX 
Test.p 


List-of-Controls example, using pop-up menu controls. 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ У 
PROGRAM Test; 


USES 
($U MemTypes.p ) MemTypes, 
($U QuickDraw.p ) QuickDraw, 
($U OSIntf .p ) OSIntf, 


($U ToolIntf .p ) ToolIntf, 
($U PackIntf .p ) PackIntf, 
($U PopMenuIntf .p ) PopMenuIntf ; 
CONST 
RES_ID = 128; (resource ID’s } 
10K = ]; ( OK button) 
iLIST = 2;( list of controls ) 
( visibility ) 
isVIS = 255; 
notVIS = 0; 
TYPE 


( Pascal equivalent of “ІМТ8” resource type ) 
IntList = record 

count: INTEGER; 

int:  erray(1..1024] of INTEGER; 
end; (IntList } 


ILPointer = ^IntList; 
ILHandle = ^ILPointer; 


VAR 
myDialog: DialogPtr; ( test dialog) 
lh: ListHandle; ( handle to list ) 
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itemHit: INTEGER; ( user's choice) 
savePort: GrafPtr; ({ to save port in) 


(Y2XXX112417.XX1X1XXX5XXXXXXXXXXX1.XXXXXXXXXXXKXXKXKEXXXXXKXKXKXKX 


CenterWindow: Centers the given window in the screen. If the 


‘show’ argument is TRUE, then the window is shown. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖ) 


PROCEDURE CenterWindow(wPtr: WindowPtr; show: Boolean); 
VAR 

pRect: Rect; 

wRect: Rect; 

h, v: INTEGER; 


BEGIN 

pRect := screenBits.bounds; 

wRect := WindowPeek(wPtr)* .port.portRect; 

v := ((pRect.bottom - pRect.top) - 
CwRect bottom - wRect.top)) div 3; 

h := ((pRect.right - pRect. left) - 
CwRect.right - wRect.left)) div 2; 

MoveWindowCwPtr, h, v, show); 

1f (show) then begin 

ShowWindowCwPtr); 


end; 
END; ( CenterWindow ) 


(Y2XXXXX1XXXXXXXXXXXXXXXX1X17XXXXXXXXXXXXXXXXXXXXKXXXKXKXKXK 
FixCtlRects: Make the contriRects of all controls in 


the list match their list rectangles, and that controls 


in invisible cells are also invisible. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


PROCEDURE FixCtlRectsClh: ListHandle); 


VAR 
ch: ControlHandle; 
i: INTEGER; 
dl: INTEGER; 
toRect : Rect; 
с: Се11; 

BEGIN 
( default ) 


dl := sizeof (Handle); 
( update the controls in the list } 
FOR i := Ø to (1h** .dataBounds bottom - 1)D0 BEGIN 
( define cell to access } 
SetPt(Point(c), 0, i); 
( get the control handle from the cell ) 
LGetCell(ëch, dl, c, 1h); 
IF (PtInRect(Point(c), 1h**.visible)) THEN 
BEGIN 
( get cell rect; copu into control rect ) 
LRect(toRect, c, 1h); 
ch**.contriRect := toRect; 
( make sure the control is visible ) 
ch^^.contrlVis := isVIS; 
END 
ELSE BEGIN 
( make sure the control is invisible ) 
ch^^.contrlVis := notVIS; 
END; 


END; 
END; (FixCtlRects ) 


(ЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖАЖАЖЖЖАХЖАЖЖАЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖХ 


FindCell: Find the cell in the given list containing 
the given point, which is assumed to be in local 
co rdinates. If the point is not in the list's 
rectangle, the resulting cell will have both 


h and v set to (- D. 
ЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У 


FUNCTION FindCell(p: Point; 1h: ListHandle): Cell; 
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VAR 
c: Cell; 


BEGIN 
with !h^* do begin 
1f (not PtInRect(p, rView)) then 
SetPt(Point(c), -1, - D 
else with rView.topLeft do begin 
c.h := ((p.h - h) DIV cellSize.h) + visible. left; 
c.v := ((p.v - v) DIV cellSize.v) + visible. top; 
end; ( else, with rView.topLeft ) 
end; (with 1h^^ ) 
FindCell := c; 
END; (FindCell ) 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


doKeyDown: Filters all keuDown events in the modal 
dialog, implementing the standard keyboard 
equivalents for the OK button. 
ЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖ ) 
FUNCTION doKeyDown(dPtr: DialogPtr; VAR theEvent: 
EventRecord; VAR itemHit: INTEGER): Boolean; 
VAR 
c: LONGINT; 
BEGIN 
( default ) 
doKeuDown := FALSE; 


( get the ascii code ) 
c := BitAnd(theEvent.message, charCodeMask); 


( check for Return or Enter ) 
IF ((c = 3) or ( c = 13)) THEN BEGIN 
itemHit := i0K; 
doKeyDown := TRUE; 
END; ( if } 
END; ( doKeyDown ) 


(ЖЖЖЖЖЖЖХЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
doMouseDown 
XOOOOCOOIOOIOOIOOOOIOOIOOROOOOOlOOloOelooooooooooooocoocooooeoeor.) 
FUNCTION doMouseDown(dPtr: DialogPtr; VAR theEvent: 
EventRecord; VAR itemHit: INTEGER): Boolean; 
VAR 

item: INTEGER; 

part: INTEGER; 

pt: Point; 

c: Cell; 

ch: ControlHandle; 

001: Boolean; 

sel: Boolean; 


BEGIN 
pt := theEvent where; 
GlobalToLocal(pt); 


( See Tech Note 8112, FindDItemC) ) 
item := FindDItemCdPtr, pt) + 1; 


IF Citem = iLIST) THEN 
BEGIN 
( in whom did the mouseDown occur? ) 
part := FindControl(pt, dPtr, ch); 


IF ((ch = nil) or (ch = 1h**.vScrol1)) THEN 
BEGIN 
( clicked in list or in scroll bar ) 
db] := LClick(pt, 
theEvent.modifiers, 
1А); 


( fix the controls’ contrlRects ) 
FixCtlRects(1h); 


END 
ELSE BEGIN ( clicked in pop-up menu ) 
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part := TrackControl(ch, pt, POINTERC- 125; 
( what cell was the mouseDown in? ) 
c := FindCell(pt, 1h); 
( redraw the control if cell was selected ) 
if (LGetSelect(false, c, 1h)) then begin 
HiliteControl(ch, titlePart); 
end; (if) 
END; ( else ) 
doMouseDown := TRUE; 
END ( item = iLIST ) 
ELSE BEGIN 
doMouseDown := FALSE; 
END; 
END; ( doMouseDown ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


doUpdateEvt 
XoXxcoooooooopooooeooeooooooooooocoooooocooooooocopbooocoooceg) 
FUNCTION doUpdateEvtCdPtr: DialogPtr; VAR theEvent: 
EventRecord; VAR itemHit: INTEGER): Boolean; 
BEGIN 

( begin the update ) 

BeginUpdateCdPtr); 


( update the dialog items ) 
UpdtDialog(dPtr, dPtr^.visRgn); 


( update the list ) 
LUpdateCdPtr^.visRgn, 1h); 


( end the update ) 
EndUpdate(dP tr); 


( always return true (we handled it) ) 
doUpdateEvt := TRUE; 
END; ( doUpdateEvt } 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
MyF ilter 
ЖЖАЖЖЖАЖЖЖАХЖАААХЖАЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖ k ) 
FUNCTION MyFilterCdPtr: DialogPtr; VAR theEvent: 
EventRecord; VAR itemHit: INTEGER): Boolean; 
BEGIN 

CASE theEvent .what ОҒ 


keyDown: 
MyF ilter := doKegDown(dPtr, theEvent, 
itemHit); 
mouseDown: 
MyFilter := doMouseDown(dPtr, theEvent, 
itemHit); 
updateEvt: 
MyFilter := doUpdateEvt(dPtr, theEvent, 
itemHit); 
OTHERWISE 


MyFilter := FALSE; 
END; ( case } 
END; ( MyFilter ) 


(Qororoooorocooroooooroooorooooooooroocorooooroocooooooooocooopoo 
DrawUserItems 
JOOOOOOODOODOOOOODODOODOOOOOOOOOOOOOOOODIOOOODOOODOOEOCOK ) 
PROCEDURE DrawUserItemsCwPtr: WindowPtr; itemNo: INTEGER); 
VAR 


savePen: PenState; 
ik: INTEGER; 

ih: Handle; 

ib: Rect; 


BEGIN ( DrawUserItems } 
( save, naormalize the pen state } 
GetPenState(savePen); 
PenNormal; 


( frame the list ) 
GetDItem(wPtr, iLIST, ik, ih, ib); 


2 


375 


FrameRect(ib); 


( frame the default button ) 
GetDItem(wPtr, 10К, ik, ih, ib); 
InsetRectCib, -4, -45; 
PenSize(3, 3); 
FrameRoundRect(Cib, 16, 16); 


( restore the pen’s state } 
SetPenStateCsavePen); 
END; ( DrawUserItems ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


ReadData: Reads in a number of controls, as specified 
by а 'INT*^ integer-array resource. Defines new 
controls for each. 

XXXXXXXXXXXKXXXXXXXXXXX1XXXXXXXXXXXKXKXXXXXXXK1XX1XKXXKXXXKX) 

FUNCTION ReadDataCdPtr: DialogPtr): Boolean; 

VAR 


ch: ControlHandle; 
iah: ILHandle; 

i: INTEGER; 

n: INTEGER; 

ignore: INTEGER; 
aCell: Cell; 

p: Point; 

aRect: Rect; 


BEGIN ( ReadData ) 
( get handle to ‘INT#’ resource } 
iah := ILHandleCGetResourceC'INT?^, RES_ID)); 


IF Ciah © nil) THEN BEGIN 
( disable list drawing } 
LDoDraw(false, 1h); 


FOR i := 1 TO iah**.count DO BEGIN 
( create a new control ) 
ch := GetNewControlCiah**.intlil, dPtr); 


IF (ch = nil) THEN LEAVE; 


( make the control visible, without drawing ) 
ch^^.contrlVis := 255; 


ignore := LAddRow(1, 32767, 1h); 
SetPt(Point(aCell), 8, i - 1); 
(5е(Се11(6сһ, sizeof (Handle), aCell, 1h); 
END; ( for ) 


( fix the controls’ contrlRects } 
FixCtlRects(1h); 


( select first control } 
SetPt(PointCaCell), 0, 0); 
LSetSelect(true, aCell, 1h); 


( enable list drawing ) 
LDoDrawCtrue, 1h); 
END; (iah O nil ) 


( return TRUE if controls were read OK ) 
ReadData := Ciah © nil); 
END; ( ReadData ) 


65555515555451335222222222222222222222 22222244, 
InitList: Define and allocate new list, into which 
will be placed a number of control handles. 
(See ReadData(), above.) 
KK KK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK +) 


PROCEDURE InitList(dPtr: DialogPtr); 


VAR 
ik: INTEGER; 
ih: Handle; 
ib: Rect; 
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dBounds: Rect; 
cSize: Point; 
BEGIN 
( set up the userItem drawing routine } 
GetDItemCdPtr, iLIST, ik, ih, ib); 
SetDItemCdPtr, iLIST, ik, HandleC@DrawUserlItems), ib); 


( inset rect, for drawing; leave room for scroll bar } 
InsetRectCib, 1, 1); 
ib.right := ib.right - 15; 


( allocate space for a single column, no rows ) 
SetRect(dBounds, 2, 0, 1, 0); 


( indicate cell size ) 
SetPt(cSize, ib.right-ib.left, 20); 


( create the list ) 

Th := LNewC ib, ( rView ) 
dBounds, ( dataBounds ) 
cSize, ( cell size ) 
RES_ID, {resource ID ) 
dPtr, ( this window) 
false, ( draw it) 
false, ( grow box ) 
false, ( sBar, horiz) 
true); ( sBar, vert ) 

END; (InitList ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖХАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖАЖАЖЖЖЖЖЖЖҖАЖЖЖЖАЖЖЖЖЖЖЖЖ 
CleanUp: Mu name is CleanUp(). You killed mu dialog. 

Prepare to die! 
ЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ') 
PROCEDURE CleanUp(dPtr: DialogPtr); 


VAR 
ch: ControlHandle; 
i: INTEGER; 
d1: INTEGER; 
c: Cell; 
BEGIN 
( default ) 


dl := sizeof (Handle); 


( indicate wait ) 
SetCursor(CGetCursor(wetchCursor 2272; 


( deallocate the controls from the list ) 

FOR i := Ø to CIh^^.dataBounds.bottom - 1) 00 BEGIN 
SetPt(Point(c), 8, i); 
LGetCell(éch, dl, c, 1h); 
DisposeControl(ch); 

END; (for) 


( dispose of the list ) 
LDispose(1h); 
( dispose of the dialog ) 
DisposDialog(dPtr); 

END; ( CleanUp ) 


(ЖЖЖЖЖЖАЖЖЖЖЖХАЖАЖЖЖЖЖХЖЖЖЖЖАЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖХЖЖ 
Main 
ААА Gaz ———— HM Г ОТЕ 
BEGIN 

( perform the ritual incantation ) 

InitGraf C@thePort); 

InitFonts; 

FlushEvents(everuEvent, 0); 

InitWindows; 

Ini tMenus ; 

TEInit; 

InitDialogsCNIL); 

InitCursor; 


( read in the dialog from its resource template ) 
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myDialog := GetNewDialog(RES_ID, NIL, POINTERC-1)); 


( create and init the list of controls ) 
InitList(myDialog); 


IF CReadDataCmyDialog)) THEN BEGIN 
( center and show the dialog } 
CenterWindow(myDialog, true); 


( save grafPort, make ours current ) 
GetPortCsavePort); 
setPor t(myDialog); 


( cycle through ModalDialog() } 
REPEAT 

ModalDialogC@MyFilter, itemHit); 
UNTIL itemHit = i0K; 


{ restore grafPort } 
SetPor tCsavePort); 
END; 
( dispose of the dialog s storage ) 
CleanUp(myDialog); 
END. ( FILE Test.p, PROGRAM Test.p } 


Listing: Test.r 


/ЖЖХХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Test.r 


Resources for List-Of-Controls example. 
DODDOODODDOOODDOODOOOOOOOOODODOODQOOOOOOOOEOOOOOOEOOOEX / 


[PPPPODOCDOOOODOOOOEIOOOERT Yp es OOoOooooooocooboooooer у 
"include "Турев.г” 
"include “PopMenuCDEF .r” 


type “INT8 2 ( 
integer = $$CountofCIntegerArray); 


array IntegerArrau ( 
integer; 

) ; 
Геки каана ре Г j nep PRHO / 
#def ine RES_ID 128 
ХХХ ребоџгсеѕжжжжжжжжжжжжжжжжжккху 
data 'LDEF^ CRES_ID, *ControlLDEF^) ( 

$$resourceC^ControllDEF.LDEF^, ‘LDEF’, 1) 


data ‘CDEF’ (pmCDEFResID, “popMenus”) ( 
$$resource(*PopMenuCDEF .CDEF”, ‘CDEF’, 1) 


resource 'DLOG^ (RESID, “RES_ID”) ( 
(54, 170, 254, 470), 
dBoxProc, 
invisible, 
noGoAway, 
0х0, 
КЕ5. 10, 
"^ 


); 
resource 'DITL^ CRES_ID, “RES_ID”) ( 
( /* array DITLarray: 3 elements */ 
/* (1) */ 
(170, 125, 190, 185), 
Button ( 
enabled, 
"OK" 
), 
/* [2] */ 
(10, 10, 72, 290), 
UserItem ( 
enabled 


ОЕ” 
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); 


resource ‘INT®’ (RES_ID, “Control ID s”) ( 


); 


(82, 10, 160, 290), 
StaticText ( 
disabled, 
"List of Controls LDEF example. ^" 


"James Plamondon, Abacus Concepts, ^ 
“1984 Bonita Avenue, Berkeley, CA ^ 


“94704.” 
) 
) 


( /* array INTArrau: 5 elements */ 
/* [1] */ 


) 


resource 'CNTL^ (128) ( 


); 


(0, 0, 0, 0), /* rect: contriRect */ 


128, /* value: menu rsrc ID*/ 
invisible, /* vis: standard  */ 
128, /* max: default menuID */ 


; /* min: default item # */ 
popMenuProc/* ProcID: 3 x / 
* mCheck, /* var: Check selection */ 
0, /* rfCon: for user's use */ 
"Thanks to: "^ /* title: standard x/ 


resource ‘MENU’ (128) { 


128, 
textMenuProc, 
allEnabled, 
enabled, 
"Thanks To: ", 
( /* 11 items */ 
“Mark Williams", 
noIcon, поКеу, noMark, plain; 
“Mark Bennet”, 
noIcon, поКеу, appleChar, plain; 
“Joseph Daniel”, 
nolcon, noKey, noMark, plain; 
"Dr. Don Morrison’, 
noIcon, поКеу, noMark, plain; 
"Andrew Stone", 
noIcon, поКеу, noMark, plain; 
"Eleanor Plamondon", 
noIcon, noKey, noMark, plain; 
“Bruce Wampler’, 
noIcon, поКеу, noMark, plain; 
"Patricia Guffey”, 
noIcon, поКеу, noMark, plain; 
"Greta Shaw", 
noIcon, noKey, noMark, plain; 
“Monty \*Montana-Unit\” Cole’, 
поІсоп, поКеу, noMark, plain; 
“Dr. Bernard Moret", 
nolcon, noKey, noMark, plain 


) 
); 
resource “CNTL (129) ( 


(0, 0, 0, 0), /* rect: contrlRect %/ 
129, /* value: rsrc ID */ 
invisible, /* vis: standard */ 
129, /* max: default menuID */ 
2, /* min: default item # */ 
popMenuProc/* ProcID: 3 x/ 

+ mRes /* var: add res names */ 
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( /* 2 items */ 

^Sub-3 Пет1”, 
noIcon, noKey, noMark, plain; 

*Sub-3 Item2", 
noIcon, noKey, noMark, plain; 


+ mCheck, /* var: Check selection */ 
‘FONT’, /* rfCon: OSType x/ 
“Fonts: “ /* title: standard */ 


) ç 
resource ‘MENU’ (129) ( 


129, “5-3 Item3”, 
tex tMenuProc, noIcon, noKey, noMark, plain 
allEnabled, 
enabled, ); 
“Fonts: ee resource 'CNTL^ (131) ( 
( /* 8 items */ (0, 0, 0, 0), /* rect: contrlRect %/ 
) 134, /* value: menu rsrc ID*/ 
); invisible, /* vis: standard  */ 
resource 'CNTL^ (138) ( 134, /* max: default menuID */ 
(0, 0, 0, 0), /* rect: contriRect */ 1, /* min: default item # */ 
130, /* value: rsrc ID */ popMenuProc/* ProcID: 3 x/ 
invisible, .  /* vis: standard  */ * mCheck, /* var: Check selection */ 
133, /* max: default menuID */ 0, /* rfCon: for user's use */ 
1, /* min: default item # */ “At Abacus: "  /* title: standard x/ 
popMenuProc  /* ProcID: 3 х / ); 
* mCheck /* var: Check selection */ resource ‘MENU’ (134) ( 
+ mSub, /* var: sub-menus */ 134, 
0, /* rfCon: for user’s use */ tex tMenuProc, 
“SubMenu: ^ /* title: standard x/ allEnabled, 
enabled, 


resource “MENU? C130) ( К ло 
130, ( /* 5 items */ 


textMenuProc, “Dan Feldman’, 
allEnabled, noIcon, noKey, noMark, plain; 
enabled, “Jim Gagnon’, 
“Root: Jh noIcon, noKey, noMark, plain; 


“Will Scoggin’, 

noIcon, noKey, noMark, plain; 
“James Plamondon", 

noIcon, noKey, noMark, plain; 
"Jay Roth’, 


( /* 2 items */ 

“Root Item1”, 
noIcon, parent, “100131”, plain; 

“Root Пет2”, 
noIcon, parent, “\@D132", plain 


) nolcon, noKeu, noMark, plain; 
); "Tiffiny Fyans", 
resource ‘MENU’ (131) ( | nolcon, noKeu, noMark, plain; 
131, "Jeanette Stafford’, 
tex tMenuProc, noIcon, noKey, noMark, plain 
allEnabled, 
enabled, ); 
rx resource 'CNTL^ (132) ( 


( уж 2 itens */ 


(0, 0, Ø, 0), /* rect: contrlRect */ 


*Sub-1 Item1^, 135, /* value: menu rsrc ID*/ 
noIcon, noKey, noMark, plain; invisible, /* vis: standard */ 
*Sub-1 Пет2”, 135, /* max: default menuID */ 


nolIcon, noKey, noMark, plain; 
“Sub-1 Item3", 
noIcon, parent, “*\00 133“, plain 


resource ‘MENU’ (132) ( 


1 /* min: default item * */ 


popMenuProc/* ProcID: 3 


х/ 


+ mCheck, /* var: Check selection */ 
0, /* rfCon: for user's use */ 
“Programs: 6 /% title: standard */ 


); 
132, \resource ‘MENU’ (135) ( 
textMenuProc, 135, 
allEnabled, textMenuProc, 
enabled, allEnabled, 
+ enabled, 


( /* 2 items */ 
*Sub-2 Пет1”, 


“Programs: ", 
( /* 5 items */ 


*StatView", 

noIcon, поКеу, noMark, plain; 
"StatView 512+”, 

noIcon, noKey, noMark, plain; 
*StatView SE*Graphics", 

noIcon, noKey, noMark, plain; 
"StetView II”, 

noIcon, noKey, noMark, plain; 


noIcon, noKey, noMark, plain; 

*Sub-2 Item2", 
noIcon, noKey, noMark, plain; 

*Sub-2 Item3 (a very, very, very wide item)”, 
noIcon, noKey, noMark, plain 


); 
resource ‘MENU’ (133) ( 


133, “Super ANOVA’, 

textMenuProc, noIcon, noKey, noMark, plain 

allEnabled, ER 
enabled, ); Sel 
"^ 


д 
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Pascal Procedures 


Build a Network Painting Program 


[Edgar Circenis: Has programmed the Mac since 1984. 
Has been employed at Nordic Software and written software for 
both the Apple |/ and Macintosh. Graduate of the University of 
Nebraska—Lincoln with a B.S. C.S. Rod Magnuson: Has had 2 
years programming the Macintosh. Founded MindVision soft- 
ware with Steve Kiene in early 1988. Co-author of MaxWrite, the 
first color word processor and MindVision' s first offering.] 

JamPaint: A Networked Paint Program 
JamPaint’s Beginnings 

Back in 1987, an AppleTalk network was installed in our 
workplace. We decided to write a simple program to allow 
communications between different nodes of this network. Our 
program, Transceive, used the NBP and LAP protocols to send 
text messages between nodes. 

When we got the program working and realized how easy it 
was to use AppleTalk, we took Transceive one step further by 
rewriting it so that a user on one Mac could draw one the screen 
of several other Macs. To do this, we created a message format 
consisting of a message type identifier and data needed for the 
given type. We implemented two different types of messages: 
Click and Drag. A click message consisted of the Click message 
identifier and a Point. The drag message took a similar form. A 
Click message was sent when a user initially clicked on the 
screen. Then, Drag messages were sentevery time that the mouse 
location changed, until the mouse button was released. 

Transceive was rewritten to operate in either master or slave 
mode. In master mode, the click and drag messages were 
generated and broadcast over the network. In slave mode, the 
messages were interpreted and the results were drawn on the 
screen. 

We relied entirely on the LAP protocol for our transmis- 
sions. This caused a problem because LAP has no facility for 
buffering incoming messages. Therefore, we experimented with 
using a VBLTask to periodically check the message buffer and 
put messages into our own buffer. This was a bad idea because 
the LAP protocol moves memory and VBLTasks cannot cause 
memory moves. Our program crashed periodically because of 
this. To solve our problem, we had to resort to polling the 
message buffer. This caused us to lose messages on occasion, but 
it was better than periodic crashes. 

Finally, we were able to have up to eight (a practical limit) 
Macs hooked up and drawing on each other’s screens simultane- 
ously. This was great fun for the staff at work, so we thought 
about the feasibility of extending Transceive into more of a paint 
program. 

Transceive sat idle for months while we thought about what 
could and couldn’t be done easily over a network. We wanted to 
keep message sizes small and had to have a system where lost 
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messages wouldn’t cause problems or crashes (with polling, 
messages will get lost). We thought about using the ATP 
protocol to avoid message loss, but decided that response time 
would be too slow for a real-time paint program. Eventually, we 
decided that LAP was still the best choice. Then, we decided to 
write JamPaint. 

JamPaint is a simple, first come, first served Networked 
Paint program. To control users, we have an array of environ- 
mentrecords. Each slot in this array is filled as unidentified users 
announce themselves (by sending an initial message) on the 
network. Again, we decided to limit the number of users to eight 
to reduce traffic on the network. JamPaint was written during a 
long weekend, but fixing bugs and adding new tools has kept us 
busy for 3-4 months. Initially, we had decided to make JamPaint 
a color paint program for the Mac II in addition to being 
networked. We wrote color code, but never spent much time 
trying to get offscreen pixmaps to work correctly. Hence, our 
screen updating was a mess on a Mac II. As soon as we get that 
code working, we will re-release JamPaint for color use on the 
Mac II. 

The Way It was Programmed 

JamPaint was written in MPW Pascal with little regard for 
proper programming technique. As a result, JamPaint variables 
are for the most part global variables. By using many globals, we 
eliminated the creation and initialization of large stack frames. 
Most of our procedure parameters are VAR parameters (to 
eliminate excessive stack frame initialization). By adopting this 
style, we were able to decrease memory usage and increase 
execution speed of our program. 

JamPaint implements eight paint tools: paint brush, letters 
tool, eraser, rectangle, filled rectangle, oval, filled oval, and a 
spray-can tool. Our palette includes eight patterns which can be 
edited by double-clicking on them. JamPaint also includes a 
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unique pen sizing tool which allows horizontal and vertical pen 
size to be set independently. We implemented the Pattern and 
Constraint keys found in most paint programs and tried to 
emulate the standard paint program user interface. 

Once again, we used the type-and-data format for sending 
our messages across AppleTalk. To make JamPaint a fully 
networked paint program, we needed to create many new mes- 
sage types. For instance, occurrences such as selecting a new tool 
had to be transmitted over the network so that each node would 
know how to handle subsequent drag messages. A problem with 
this approach is thata tool selection message may be lost and drag 
message may be mis-interpreted. Fortunately, with only eight 
nodes, this doesn't happen often. 

With JamPaint, we eliminated the master/slave modes used 
in Transceive and put all nodes in a combined master/slave mode. 
What this means is that every message incoming from a previ- 
ously identified node will be executed. Also, every action 
performed locally will be broadcast. 

To handle the transmission and execution of command 
messages, we implemented a simple command queue. Every 
incoming message is put into this queue, and periodically, the 
first message in the queue is executed. To save ourselves the 
trouble of duplicating this mechanism for local actions, and to 
simplify the testing of the incoming message routines, outgoing 
messages are broadcast and then put into the incoming message 
queue for execution locally. This way, all drawing gets handled 
by the same set of routines. Our approach not only cut down on 
code size, but simplified debugging and streamlined our message 
handling system. 

How Things Get Drawn 

JamPaint uses an offscreen bitmap to perform its updating 
and redraw. All drawing commands are duplicated — once for 
the screen, and once for an offscreen bitmap. When an update is 
required, CopyBits is used to transfer the image back onto the 
screen. This approach was made necessary when we decided that 
our window wouldn't always be the front window (because of 
DA’s, dialogs, etc.). 

The Users on the Network 

JamPaint treats each user as a paint environment. Whena 
user first starts using JamPaint, a message corresponding to their 
first action is broadcast over the network. Any nodes that still 
have room in their environment tables (remember, only eight 
entries) will notice that this message comes from an unidentified 
node. They will then request that the sending node transmit its 
environment. The same happens in the other direction. The new 
node will not recognize the already operating nodes and will fill 
its own environment tables the same way. 

The following data structure is used to keep track of a user 
environment: 


UserTableRec = record 
id: integer; 
time: longint; 
theTool: integer; 
x,y: integer; 
theMode :boolean; 


( AppleTalk ID number ) 

( time elapsed since lest message sent ) 
( current pain tool ) 
( last pen coordinate ) 
( line or dot mode ) 


thePat pattern; ( penPat ) 
theClr:R6BColor ; ( color for Mac II ) 
hSize,vSize:integer; ( pen size ) 
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( font number ) 

( font size ) 

( font style ) 

( splatter radius for airbrush ) 
( splatter speed for airbrush ) 


theFnum: integer; 

theFsize: integer; 

theFstyle:style; 

sp latRad: integer; 

sp latSpeed: integer; 

end; 

id: The AppleTalk node id of the user. This is needed to 
send our messages through the LAP protocol calls. 

time : The TickCount value of the last time a message from 
the user was executed. This is used to eliminate 
“dead” users from the network. 

theTool : is the current tool for the user. 

x, y : The current pen position of the user. 

theMode : The current mode of the user. JamPaint supports 
two drawing modes: line and dot. In line mode, drag 
packets connect the current x,y position with a line to 
the previous position. In Dot mode, no connection is 
made. 

splatRad : The airbrush radius; double clicking on the 
spray-can tool will bring up a dialog that allows the 
airbrush radius to be resized. 

splatSpeed : The airbrush speed, or how many particles get 
sprayed each time a drag message is received; this 
can also be changed by double-clicking the spray-can 
tool. 


Packet Types 
The following is the variant data structure used for the 
different message types in JamPaint: 


MSGType=(paintMode, alpha, settool,eraseall,setpat,setcolor,setpen, 
setfont, setpos,drag,rectpck,setSplat,rqinfo,sendinfo); 


LAPMsg = record 


size :packed array [0..1] of byte; 
theType :MSGType; 
id : byte; 


case MSGType of 
paintMode : (mode : boolean); 
alpha: (ch:char);{ type char in current font,size,style 
, location } 
settool:(tool: integer); ( select а tool ) 
setpat:(pat:pattern); ( select a pattern ) 
setcolor:(clr:RGBColor); ( select a color ) 
setpen:(px,py:integer); ( set pen size to px,py } 
setfont:(fnum: integer; ( select font characteristics ) 
fsize: integer; 
fstyl:style); 
setpos:(mx,my: integer); ( set current position to mx,my ) 
drag:(cx,cy: integer); ( mouse dragged from mx,my to cx,cy ) 
setSplat:(sRad: integer; ( resize splatter tool ) 
sSpeed: integer ); 
rectpck:(rct:rect; 
op tDown: boolean); 
sendinfo:Cinfo:UserTableRec); ( user info } 


end; 


( rectangle for TRect..TFOval ) 


All paint functions are executed by transmitting one of these 
message data structures to the users on the network. 


Implementing Tools That Require Waiting 


Implementing the oval and rectangle drawing tools was 
more difficult than implementing the other tools. This is due to 
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the fact that these objects can be enlarged and shrunken before 
actually being placed into a document. With messages coming 
In from other machines, we had to address the problem of what 
to do while the user was sizing an object. Also, we had to worry 
about how resizing was to be done on a remote machine. 

We decided that it would be a waste of code and time to 
resize objects on a remote screen. After all, the finished object 
was what we were after. This left only the problem of how to 
handleresizing locally while executing incoming messages. Our 
solution was to do all resizing on the screen only. We would leave 
the offscreen bitmap alone until the object was complete. All 
incoming messages get executed on the offscreen bitmap and 
updated to the screen. Then, when the sized object is complete, 
a message is transmitted to draw it both locally and elsewhere. 
This way, we reduce AppleTalk traffic, eliminate the problem of 
missed messages, and avoid over-writing of previous drawing. 


Drag Packets 

Whenever a user is holding down the mouse, drag messages 
are transmitted (unless the rectangle or oval tools are selected). 
Drag messages contain only the new location of the mouse. 
When a Drag message is received, it is sent to one of the drawing 
routines depending on the current tool in the environment record 
for the user in question. This local interpretation of commands 
was chosen because it results in smaller AppleTalk packets, 
leading to better throughput. 


JamPaint’s Future 
Is there a future for JamPaint? We think so. Anyone who has 
played (yes, it’s more like playing than painting) with JamPaint 
has to admit that it was fun. We plan to enhance JamPaint by 
making it into a real paint program. Planned enhancements 
include: 
° Color 
° Separate palette and tool windows with more patterns and 
tools. 
° A full page (or possibly oversize) drawing surface. 
° Selection tools. 
° Special effects (fades, contrast enhancement, smoothing, 
etc.). 
* Paint channels and privacy mode. 
* Object-oriented drawing. 
• Enhance compatibility with existing paint programs. 
° Memos. 


We would like to think that JamPaint is a step into the future. 
JamPaintisanew kind of tool which not only allows many people 
to see the same piece of work, but to also modify it. Weare trying 
to bring real connectivity to the Mac by creating multi-user 
software. 

We ask that you do not change JamPaint and distribute it. It 
has been copy righted. To maintain some sort of order, and 
minimize confusion, MindVision Software will gladly accept 
suggestions for improvements to this program. If you would like 
to add something to JamPaint, let us know what you're doing and 
maybe we can work together. Our About Window has room for 
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plenty of names; just don't expect to become rich. 


After Thought 

We suggest that you run JamPaint on System 4.1 or 4.2 
because JamPaint is very slow running under System Software 
6.0. We do not know why this is. We haven't had time to look 
into it yet. 

We have also noted that Apple has implemented something 
similar to JamPaint in HyperCard with their XCMD set that 
allows access to NBP and LAP AppleTalk protocols from script. 


Listing: MekeFile.p 

BERRA JamPaint MakeFile #9999 
Pascal = Pascal 

POptions = -s 


ро fp 
Pascal -k "(PLibraries)^ (default).p 


JamPaint Í JamPaint.r JamPaint.code 
Rez "(RIncludes)"Tygpes.r JamPaint.r -o JamPaint -c JPNT 
SetFile -a B -d . JamPaint 
JamPaint.code f JamPaint.p.o 
Link JamPaint.p.o ò 
”(Libraries)}”Interface.o à 
*(PLibraries)“Paslib.o à 
“(Libraries}”“Runtime.o à 
-0 JamPaint.code 
== = U il u eg ЕЕ 
Listing: JamPaint.p 
Program JamPaint; 
(ЖЖЖЖ 


JamPaint — the Network Paint Application 
ЖЖЖЖЖЖАЖЖХЖАЖЖХАЖЖЖЖЖХЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Copuright 1988 bu Edgar Circenis and Rod Magnuson 
All Rights Reserved 


X XC oko KKK ARK K KKK KKK KK KKK KKK KKK KKK EK KKK KKK EEK KEKE 


Started: 12/26/87 Revision: 5/21/88 
KRKKKKK KKK KKK KKK EKER KKK KK KKK KKK KEK KKK KKK KKK KK KKK 
Problem areas: 
- Do we need to worry about nets as well as nodes? 
- How big should PQ be? 
- VBLTasks cannot move memory. 
- Change xEnqueue and xDequeue to access PQ directly. 
- What causes initial LAPWrite error 670 (err = -95)??? 
- NOTE: if we end up using polling, a queue will be 
unnecessary. 
- use VAR parameters where it will speed things up. 
ЖЖЖЖ ЖКК) 
USES 
($LOAD MacDump) 
Memtypes, Quickdraw, OSIntf ,ToolIntf,PackIntf,PickerIntf, 


Script, 
($LOAD AppleTalkDump) 
AppleTalk, 
($LOAD MacPrintDump) 
PrintTraps; 
CONST 
lestMenu = 7; 
maxUsers = 8; ( User Table size ) 
Our Type = 39; (са random LAP protocol type ) 
listSize = 550; ( incoming packet queue size ) 
VBLcnt = 2; ( myTask.vblCount ) 
connect - false; 
Spray - true; 
idleTime = 60*60*5; ( five minute idle time ) 


eraseCursor = 128; 
splatCursor = 8088; 


( splatter cursor ID ) 
( — TOOLS — ) 
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Tnone = 0; ( по tool, ог special tool ) 
Tsprag = 1; ( not reallu a tool! ) 
TLetters = 2; ( letter tool } 

Tbrush = 3; ( paint brush } 

Terase = 4; ( eraser } 

TRect = 5; { Rectangle } 

TFrect = б; { Filled Rectangle } 
TOval = 7; ( Oval } 

TFOval = 8; ( Filled Oval } 
TSplatter= 9; ( Splatter Too) ) 
TDisk = 10; ( Disk Access } 
Tpat = 11; ( not a tool ) 
Tcolor = 12; ( not a tool ) 

( — DEFAULTS — } 

dSize = 12; 

dStyle = []; 

dPen = 1;{ 1x 1 pen } 

dColor = 1; { black } 

dToo] = Tbrush; 

dMode = connect; 


dsplatterCount = 30;( * default spatter speed * } 
dsplatRad = 20; ( * default splatter radius * } 

( **** make a decision about this and delete it **** ) 
polling = true; 


TYPE 


appleMenu = 1; 

fileMenu = 2; 

fontMenu = 3; 

sizeMenu = 4; 

styleMenu = 5; 

effectsMenu= 6, 

editMenu = 7; 

UserTableRec = record 
id : integer; ( appleTalk id ) 
time : longint; ( idle time ) 
theToo1 : integer; ( current too! ) 
х,у : integer; ( mouse coordinates ) 
theMode ‘boolean; ( paint mode } 
thePat pattern; ( current pattern ) 
theClr  :R6BColor;  ( current color ) 
hSize, vSize: integer; ( penSize ) 
theFnum : integer; ( font number ) 
theFsize : integer; ( font size ) 
theFstyle :style; ( font style ) 
splatRed :integer; ( splatter’s radius ) 
splatSpeed :integer; ( splatter's speed ) 

end; 


MSGType = C(paintMode,alpha,settool,eraseall,setpat 


,setcolor, setpen, setfont, setpos, drag, rectpck, setSplat,rqinfo, sendinfo); 


LAPMsg = record 


size ‘packed array [0..1] of byte; (packet length) 
theType :MSGType; ( message type ) 
id ‘byte; ( node id } 


case MSGType of 
paintMode: (mode :boolean); 
( select paint mode type: connect, spray ) 
alpha: (ch :char); 
( type char in current font, size, style, location } 


settool: (tool integer); ( select a tool ) 
setpat: (раї :pattern); ( select a pattern ) 
setcolor: (clr :RGBColor); { select а color } 
setpen:  (px,py: integer); (set pen size to px,py ) 
setfont: (fnum :integer; ( font characteristics ) 


fsize: integer; 
fstyl:style); 
Setpos: (mx,my: integer); (set position to mx,my) 
drag: Ccx,cy: integer); 
( mouse dragged from mx,my to cx,cy ) 
setSplat: (sRad: integer; (тезе splatter tool ) 
sSpeed: integer ); 


rectpck: (гсісгесі; (rectangle for TRect..TFOval) 
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optDown 
sendinfo: 


end; 
LAPMsgPtr = ^LAPMsg; 


:boolean?; 
Cinfo :UserTableRec); ( user info ) 


PacketList = Packed array [8..listSize-1] of LAPMsg; 


PacketQueue -record 


head  : integer; 

tail  :integer; 

queue :PacketL ist; 
end; 


PacketQueuePtr = ^PacketQueue; 


CArry 
CPtr = “CArry; 
CHandle = ^CPtr; 


BitMapPtr = “BitMap; 
VAR 
( A NOTE ABOUT GLOBALS 


= Array (1..8] of RGBColor; 


AND SUCH: 


Everyone is taught that using global variables is asin. We 


do not agree. 


By using many globals and declaring parameters 


in parameter lists to be VAR parameters Ceven when not 
needed), we increase the speed of our code by reducing stack 


frame size and the creation 


of local copies of variables.) 


myEvent :EventRecord; 
theItem, theMenu, refnum : integer; 
theChar : Cher; 

code : integer; 
tempWindow,myWindow | :WindowPtr; 
donef lag ‘boolean; 
PrDebug :boolean; 

mods : longint; 
mymenus ‘array [1..lastmenu] of MenuHandle; 
F i leMenuPresent ‘boolean; 

err : integer; 

dig :DialogPtr; 
itype : integer; 

item :handle; 

box ‘rect; 

itemHit : integer; 
myTask : VBLTask ; 

UT ‘array [@..maxUsers] of UserTableRec; 
PQ :Packe tQueue ; 
myNode , myNe t : integer; 

LAPrh, LAPwh : ABRecHandle; 
LAPrbuf , LAPwbuf :LAPMsg; 
DrawWindow :WindowPtr; 
drect,prect :rect; 

jamPic, palette :picHandle; 
ToolRects :arrag[1..20] of Rect; 
curPatRect ‘rect; 
hSizeRect, vSizeRect :rect; 
PatternsUp ‘Boolean; 

thePat terns ‘array [1..8] of pattern; 
theColors :CArru; 
curPat, curColor : integer; 

theF ont idx : integer; 
іһебігеідх : integer; 
clickTime : longint; 
1а5%7001 : integer; 
theECurs, theCurs : cursor; 
arrowCurs,updateCurs  :boolean; 
bmap,Wbits ‘bitmap; 
OldRgn,oldClip :RgnHandle; 
changed, saved :boolean; 
fVref : integer; 

Mul tiF inderRunning ‘boolean; 
ColorQDrawImp im ‘boolean; 
MacII,PixDraw :boolean; 
myCGraf Ptr :CorefPtr; 
myCGrafPort :CGraf Port; 
ourCMHandle : CTebHandle; 
offpix,Wpix :PixMapHandle; 
theHand, theSizer : CursHandle; 
theSprayer , theP lacer : CursHandle; 


@ The Best of MacTutor, Vol. 5 


hPrint :THPrint; begin 
if errog then 


Procedure SendLAP(who:byte); Forward; begin 
Procedure CheckRead; Forward; if prDebug then 
Procedure DrawContents; Forward; Debug(concat('*** “ өіг(і),”: error = “,str(err))) 
else 
Procedure Debug(s:str255); menustring(concat(str(i),’: error = “,str(err))); 
begin end; 
if PrDebug then end; 
begin 
PrCtlCallCiPrIOCt],ordC8s2*1, length(s),@); Procedure RsrcErr; 
PrCtlCallCiPrDevCt1,$0003FFFF , 0,0); begin 
end; if ResError o2 then 
end; begin 
if PrDebug then 
Function StrCi:longInt?:str255; Debug(concat(^*** RsrcErr=’,str(ResError))) 
( These two functions are invaluable ) else 
begin menuStr ingCconcat( ‘RsrcErr=’,str(ResError))); 
NumToStringCi,Str); end; 
end; end; 
Function Val(s:str255): longint; Procedure SetUpMenus; 
begin var 
StringToNum(s, Val); i : integer; 
end; s,fName :str255; 
begin 
function MyGetNextEventCevtMask: Integer VAR InitMenus; 
Evt:EventRecord) :Boolean; FileMenuPresent :=false; 
( * This allows us to be more MultiFinder compatible * } for i := 1 to lastmenu do 
begin MyMenus[il := GetMenu(254* i); 
If MultiFinderRunning then for i := 1 to lastmenu-1 do 
MyGetNextEvent:-WaitNextEventCevtMask,Evt, 15, Ni1) InsertMenuC(nyMenus[ i 1,0); 
else AddResMenu(MyMenus [app eMenu! , "DRVR ); 
begin AddResMenu(MyMenus [f ontMenu  , "FONT ^); 
SystemTask ; GetFontNameCapplFont, f Name); 
MyGetNextEvent:zGetNextEventCevtMask,Evt); for i := 1 to countMI tems(mymenus[fontMenu]) do 
end, begin 
end; GetItemC(mymenus [f ontMenu], i,s); 
if s-fName then 
Procedure MenuString(s:str255); (debugging simple stuff } begin 
var CheckItem(mymenus [f ontMenu], i, true); 
dMenu :MenuHandle; theFontidx := i; 
begin leave; 
S := Concat(s,’ «click ^); end; 
DMenu := NewMenu(999,s); end; 
InsertMenu(CDMenu, 8); for i:=1 to 9 do 
DrawMenuBar ; begin 
sysBeep( 1); GetI tem(myMenus[sizeMenu],i,s); 
repeat Until 1f RealFont(theFontidx, Val(s)) 
Мубе tNex tEvent(mdownMask+keyDownMask+AutoKeyMask , nyEvent); then 
Dele teMenu(999); SetI temStyleCmyMenus[sizeMenu], i, (Outline)) 
DisposeMenu(DMenu); else 
DrawMenuBar ; SetI temStyleCmyMenus[sizeMenu],i,[1); 
end; end; 
DrawMenuBar ; 
Function idleFilterCitem: Integer; theD1g:DialogPtr): Integer; end; 
begin 
Se tUpAS ; Procedure xEnqueue(var msg:LAPMsg); ( add queue element ) 
idleFilter:=item; begin 
CheckRead; Debug( ‘xEnqueue’ ); 
RestoreA5; with PQ do 
end, if (tail*1) mod listSize = head then 
begin 
procedure HiliteButtonCtheDialog:DialogPtr); sysbeep(1); ( oops, queue full! ) 
begin Debug( ‘Queue Full’); 
SetPort( theDialog); end 
GetDItemCtheDialog,ok, iType, iTem, Box); else 
InsetRect(Box,-4,-4); begin 
PenSize(3,3); queue[tail] := msg; 
FrameRoundRect(box, 15, 16); tail := (tail+1) mod listSize; 
PenNormal; Debug(concat(' head=’,str(head),’, tail=’,str(tail))); 
end; end; 
end; 


Procedure DoErr(i: integer); 
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Function xDequeue(var msg:LAPMsg?:boolean; ( remove first 
queue element ) 
begin 
with PQ do 
і? tail-head then 
xDequeue := false 
else 
begin 
Debug ‘xDequeue: dequeued'); 
msg := queue[head); 
head := (head*1) mod listsize; 
xDequeue := true; 
Debug(concat(’ head=’,str(Chead),’, tailz^,strCtail02); 
end; 
end; 


procedure DoPageSetUp; 
var 
temphPrint : THPrint; 
err : OSErr; 
begin 
PrOpen; 
If PrError=noErr then 
begin 
temphPr int :=hPrint; 
err :=HandToHandChand1e( temphPr int) ); 
Repeat 
if PrStiDialog(temphPrint) then 
begin 
DisposHandleChandleChPr int )); 
If МепЕггог o NoErr then 
SysBeep(C 1); 
hPrint:=temphPr int; 
err :-HandToHandChandleChPr int )); 
if err©NoErr then 
SysBeep( 1); 


end; 
Until not PrValidateChPr int); 
end; 
PrClose; 
DisposHandleChandleCtemphPr int )); 
end; 


Function FindUserCid: integer): integer; ( find UT entry ) 

( find user in UT. If not in UT, return -1 and send 
«rqinfo? packet to user if table not yet full. If data is not 
valid, returns -Cindex*1). ) 

var 
i : integer; 
begin 
Debug( ‘F indUser ^); 
for i :- 0 to maxUsers do ( CASE 1: look for user ) 
if UTli].id=id then 
begin 
FindUser := i; 
Debug(C' user found’); 
exit(FindUser ); 
end; 
Debug(’ user not found’); 
for i := 1 to maxUsers do (CASE 2:look for empty slot) 
if UT[i).ide0 then 
begin 
UTLil.id := id; 
LAPwbuf . theType := rqinfo; 
SendLAPCid); 
FindUser := -1; (user not valid (yet) ) 
exitCF indUser ); 
end; 
for i := 1 to mexUsers do (CASE 3:look for idle user) 
if tickCount-UT[il.time» idleTime then 
begin 
UT(il.id := id; 
LAPwbuf . theType := rqinfo; 
SendLAP( id); 


( valid user found ) 
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FindUser := -1; 
exit(FindUser ); 
end; 


( user not valid Cyet) } 


end; 


Procedure SetUserState(j: integer); { set previous state } 
begin 
Debug( ‘SetUserState’); 
with UT[j] do 
begin 
Movelo(x,y); 
PenPat( thePat); 
if MacII then 
RGBForeColor(theCir); 
PenSizeChSize,vSize); 
TextFontCtheFnum); 
TextSizeCtheFsize); 
TextFaceCtheFstyle); 
end; 
end; 


Procedure OffBits; 
begin 
if MacII then 
begin 
if PixDraw then 
begin 
SetPort(GrafPtr(myCGrafPtr )); 
end; 
end 
else 
begin 
01dRgn:=NewRgn; 
CopyRgnCDrawW indow* .visRgn, oldRgn); 
RectRgnCDrawW indow^ .visRgn, bmap .bounds); 
Wbits:-DrawWindow^ .portbits; 
SetPortBits(bmap); 
end; 
end; 


( set offscreen bitmap ) 


Procedure OnBits; 
begin 
if MacII 
then 
begin 
if PixDraw then 
begin 
SetPor t(DrawW indow); 
end; 
end 
else 
begin 
CopyRgnColdRgn, Оган indow^ .visRgn); 
DisposeRgn(oldRgn); 
se tPor t(DrawW indow ); 
setPortBitsCWbits); 
end; 


( set onscreen bitmap ) 


end; 


Procedure DoSplatter(user: integer); 


var 
r ‘rect; 
1,хх,уу : integer; 
begin 
ClipRect(drect); 


with UT[user] do 
for i := 1 to splatSpeed do 
begin 

repeat 
xx := random mod SplatRad; 
yy := random mod SplatRad; 

until xx*xxtyy*yy <= SplatRad*SplatRad; 

ХХ .= XX + x; 
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SetRect(r, xx, yy, xxthSize, yytvSize); 
PaintRect(r); 

OffBits; 

PaintRect(r); 

OnBits; 

end; 
ClipRect(drawWindow* .portRect); 
end; 


Procedure DoRect(utnum: integer ;r:rect;optDown: boolean); 
( handle rect packets } 
begin 
Debug( ‘DoRect ^); 
with UT[utnum] do 
case theTool of 
TRect: begin 
if not optDown then 
PenPat(black); 
FrameRect(r); 
OffBits; 
FrameRect(r); 
OnBits; 
end; 
TFRect: begin 
PaintRect(r); 
OffBits; 
PaintRect(r); 
OnBits; 
1f not optDown then 
begin 
PenPat(black); 
FrameRect(r); 
OffBits; 
FrameRect(r); 
OnBits; 
end; 
end; 
TOval: begin 
if not optDown then 
PenPat(b lack); 
FrameQval(r); 
OffBits; 
FrameOval(r); 
OnBits; 
end; 
TFOval: begin 
PaintOval(r); 
OffBits; 
PaintOval(r); 
OnBits; 
1f not optDown then 
begin 
PenPat(black); 
FrameOval(r); 
OffBits; 
FrameQval(r); 
OnBits; 
end; 
end; 
end; 
end; 


Procedure DoDrag(utnum,dx,dy: integer); (drag packets) 

var 

pt ‘point; 

r ‘rect; 
begin 

DebugC ‘DoDrag’); 

with UT[utnum] do 

case theToo! of 
Tbrush: begin 
if theMode=connect then 
begin 
GetPen(pt); 
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LineToCdx, dy); 
OffBits; 


MoveTo(pt.h,pt.v); 


LineToCdx, dy); 
OnBits; 

end 

else 

begin 
MoveTo(Cdx, dy); 
Line(0,0); 
OffBits; 
Movelo(dx,du); 
Line(0,0); 
OnBits; 

end; 


end; 
Terase: begin 
penPat(white); 


1f theMode=connect then 


begin 
GetPen(pt); 
LineTo(dx,du); 
OffBits; 


Movelo(pt.h,pt.v); 


LineTo(dx,du); 
OnBits; 

end 

else 

begin 
Movelo(dx,du); 
Line(0,0); 
OffBits; 
Movelo(dx,du); 
Line(0,0); 
OnBits; 

end; 


end; 
TSplatter: begin 
x :7 dx; 
у := dy; 
DoSplatterCutnum); 
end; 
end; 
end; 


Procedure SendMyInfoCid: integer); ( send UT to node «id» ) 


begin 
Debug( 'SendMyInfo"^); 
with LAPwbuf do 
begin 
theType := sendinfo; 
info := 07[@]; 
end; 
беп АРС14); 
end; 


Procedure DebugLAPTupe(t:MSGTupe); 
begin 
case t of 

paintMode: Debug(' paintMode’); 
alpha: Debug(’ alpha’); 
settool: Debug’ settool’); 
eraseall: Debug(' eraseall’); 
setpat: Debug(' setpat’); 
setcolor: Debug‘ setcolor’); 


Setpen: Debug(‘ setpen’); 
setfont: Debug(’ setfont’); 
Setpos: Debug(^ setpos’); 
drag: Debug(’ drag’); 


rectpck: Debug(’ rect’); 
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rqinfo: беоиас” rqinfo’); 
sendinfo: Debug’ sendinfo’); 
end; 
end; 


Procedure ExecMessage(var nsg:LAPMsg); ( handle a LAP 
message ) 
var 
j : integer; 
pt :point; 
savePort :GrafPtr; 
begin 
Debug( ‘ExecMessage’ 2; 
changed := true; 
with msg do 
if theType=rqInfo then ( handle rqInfo requests } 
begin 
SendMyInfoCid); 
DebugLAPType( the Type); 
end 
else ( handle graphics commands } 
begin 
GetPor tCsavePor (0; 
SetPor t (DrawW indow); 
j := FindUserCid); (дес index into user table ) 
if j»=0 then 
begin 
SetUserState(j); ( set user’s port state } 
with UT[j] do 
begin 
DebugLAPType( theType); 
case theType of 
paintMode: theMode := mode; 
alpha: begin 
GetPen(pt); 
DrawChar (ch); 
OffBits; 
MoveTo(pt.h,pt.v); 
DrawChar (ch); 
OnBits; 
GetPen(pt); 
x := pt.h; 
pt.v; 


y: 
end; 
eraseall: begin 
eraseRect(drect); 
Of fBits; 
eraseRect(drect); 
OnBits; 
end; 
settool: theTool := tool; 
setpat: thePat := pat, 
setcolor:theClr := clr; 
setpen: begin 


hSize := px; 
vSize := py; 
end; 


setfont: begin 
theFnum := fnum; 
theFsize := fsize; 
theFstyle := fstyl; 


end; 
setpos: begin 
x :7 mx; 
y := my; 
end; 


drag: DoDrag(j,cx,cu); 
rectpck: DoRect(j,rct,optDown); 
setSplat: begin 
splatRad := sRad; 
splatSpeed := sSpeed; 
end; 
sendinfo: begin 
UT(j] := info; 
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DebugC^ sendInfo received’); 
end; 
end; 
time := tickCount; 
end; 


( user is active ) 


end 
else 
Debug(’ msg not executed’); 
SetPor t(savePort); 
end; 
end; 


Procedure CheckQueue; (execute packet from incoming queue) 
var 
msg :LAPMsg; 


if polling then 
CheckRead; 
if xDequeue(msg) then  ( incoming queue ) 
ExecMessage(msg); 
end; 


Procedure SendLAP(who:byte); (send LAP Packt to node <id>} 
var 
sz  :longint; 
begin 
Debug( 'SendLAP'); 
DebugLAPTgpeCLAPwbuf . theType); 
(5999599599 THIS NEEDS TO BE RECALCULATED! 22232233213) 
case LAPwbuf .theType of 
paintMode,alpha,settool: sz := 2; 
eraseall: 52 ; 


setpat: sz := sizeof (pattern); 
setcolor: sz := Sizeof (RGBColor); 
setfont: sz := sizeof(style) + 4; 
setpos,setpen,drag: 62 := 4; 
rectpck: sz := sizeof(rect)+2; 
sendinfo: 62 := sizeof (UserTableRec); 
setSplat: sz := 4; 

end; 


sz := sizeof (MSGTupe)+4+sz; ( LAP packet size ) 
Sz := Sizeof (LAPMsg); ( «- DEBUGGING ONLY ) 
with LAPwbuf do ( set up LAP packet size, sender id ) 


begin 
id := muNode; 
size[0] := sz div 256; 
size[1] := sz mod 256; 
end; 
with LAPwh^^ do 
begin 


lepAddress.lapProtType := OurType; (protocol type) 
lepAddress.dstNodeID := who; ( destination node ) 
lapReqCount := sz; ( packet size ) 
lapDataPtr := @LAPwbuf; ( packet data pointer ) 
end; 
err := LAPWriteCLAPwh,false); ( send LAP packet } 
DoErr( 78); 
1f LAPwbuf.theType < rqInfo then 
( don’t want to execute rqInfo or sendInfo locally ) 
ExecMessage(LAPwbuf); ( execute message locally ) 
end; 


Procedure CheckRead; 
var 
destnode : integer; 
begin 
SetUpA5; 
err := LAPrh**.abResult; 
if err=0 then 
begin 
Debug ‘CheckRead: msg rcvd’); 
DebugLAPTypeCLAPrbuf . theType); 
destNode := LAPrh**.]lapAddress.dstNode ID; 
if (destNode=255) or (destNode-myNode) then 
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xEnqueue(LAPrbuf 2; 


end; 
if erro1 then 


begin 
with LAPrh** do 
begin 
lapAddress.lapProtType := OurType; 
lapReqCount := Sizeof CLAPMsg); 
lepDataPtr := @LAPrbuf; 
end; 
err := LAPRead(LAPrh, true); 
DoErr (5808); 
end; 
myTask.vblCount := VBLCnt; 
RestoreA5; 
end, 
Procedure SetUpRead; 
begin 
with LAPrh** do 
begin 


lapAddress.lapProtTupe := OurType; 
lepReqCount := Sizeof CLAPMsg?; 
lapDataPtr := @LAPrbuf ; 
end; 
err := LAPRead(LAPrh, true); 
DoErr(71); 
if not polling then 
begin 
with myTask do 
begin 
аТуре := ord(vType); 
vblAddr := @CheckRead; 


vblCount := VBLCnt; 
vblPhase := VBLCnt div 2 + 1; 
end; 
err := VInstallCémyTask); 
боЕгг(500); 
end; 
end; 
Procedure DisplauPatterns; 
var 
i : integer; 
begin 


for i := 1 to 8 do 
FillRectCtoolRects[i* 12], thePatterns[i 12; 
FillRectCcurPatRect, thePatterns[curPat 12; 
end; 


Procedure DisplayColors; 
var 
1 ; integer; 
begin 
PenNormal ; 
for i := 1 to 8 do 
begin 
ReGBForeColor(CtheColors[il2; 
PaintRect(toolRectsli+12]); 
end; 
RGBForeColor(theColors(curColor 12; 
PaintRectCcurPatRect); 
end; 


Procedure DrewPalette; 
var 
r rect; 
begin 
SetPor t(DrawW indow); 
DrawPicture(Cpalette, prect); 
with UTIS] do 
begin 
InvertRect(toolRects[theToo1]); 
1f not theMode then 
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with toolRects[theTool]do 
begin 
PenModeCPatXOR); 
PenPatC1tgrau?; 
PaintRectCtoolRects[Tspray12; 
PenNormal; 
end; 
end; 
PenModeCPatXOR); 
PenPat(C1tgray); 
if PatternsUp then 
begin 
PaintRectCtoolRects[Tcolor 10; 
PenNormal; 
DisplagPatterns; 
end 
else 
begin 
PaintRect(toolRects[Tpat]); 
PenNormal ; 
DisplayColors; 
end; 
with vSizeRect,UT[0] do 
SetRect(r, left, top+(vSize-1)*2,right, top*vSize*2); 
InvertRect(r); 
with hSizeRect,UTI(2] do 
SetRect(r, left, top+(hSize-1)*2, right, topthSize*2); 
InvertRect(r); 
dus current tools, modes, pattern/color, pensize) 
end; 


Procedure OpenBitMap(r:rect); ( create offscreen bitməp ) 
var 


pb ‘Bitmap; 
xx, yy, SN :Longint; 
1 : Integer; 


saveGDevice :GDHandle; 
maxGDev ice : GDHandle; 
theDepth : Integer; 
offRowBytes  :Longint; 
size0f0f f :LongInt; 
begin 
if MacII then 
begin 
if PixDraw then 
begin 
х Pix Мар Mak’in х } 
saveGDev ice :=GetGDevice; 
maxGDev ice :=GetMaxDevice(screenBits.Bounds); 
SetGDev iceCmaxGDevice); 
myCGrafPtr :=@myCGrafPort; 
OpenCPor t(myCGrafPtr); 
theDepth :=myCGrafPtr*.portPixMap** .pixelSize; 
with r do 
begin 
of fRowBytes :=(C CC theDepth*(right-left))+15) DIV 16)*2; 
sizeOfOff :=LongIntCbottom-top )*of fRowBytes; 
end; 
with myCGrafPtr* .portPixMap** do 
begin 
DisposP tr CbaseAddr ); 
baseAddr : sNewPtr(sizeOfOff 5; 
rowBytes:-of fRowBytes+$8000 ; 
bounds : =r; 
end; 
ourCMHand le :=maxGDev ice**.gdpMap** .pmTable; 
err :=HandToHand(hand]e(CourCMHand le ) ); 
If ErróNoErr then 
SysBeep( 1); 
($R-) 


with ourCMHandle^^ do 
begin 
for і:-0 to ctSize do 
ctTableli].value:=i; 
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transIndex:=BAND(transIndex,$7FFF); 
end; 

($R+) 

myCGrafPtr^.portPixMap^^.pmTable:-ourCMHandle; 

bmap:-BitMapPtr(mgCGrafPtr^ .portPixMap^2^; 
Woits:=BitMapPtr(CGrafP tr (DrawW indow)*.portPixMap* )*; 

SetPor t(GrafPtr(myCGrafPtr)); 

EraseRect(thePort* .portRect); 

SetPor t (DrawW indow); 

SetGDeviceCsaveGDevice?; 

end; 


xx := right- left; 
yy := bottom-top; 


sn := ((xx+15) div 16)*2*yy; 
with bmap do 
begin 
bounds := r; 
rowBytes := 
BaseAddr := 
end; 
pb := DrawWindow^ .portbits; 
SetPortBits(bmap); 
ClipRect(r); 
RectRgn(DrawW indow^ . visRgn,r2; 
EraseRect(r); 
SetPortBits(pb); 
ClipRectCDrewWindow^ .portRect); 
RectRgnCDrawW indow^ .visRgn, DrawWindow* .portRect); 
Wbits:=DrawWindow* .portbits; 
end; 
end; 


((хх+ 15) div 16)*2; 
NewPtr(sn); 


Procedure OpenDrawWindow; ( initialize drawing window } 
var 
r ‘rect; 
begin 
1f MacII then 
DrawWindow := GetNewCWindow( 129,ni1,pointer(-1)) 


else 
DrawWindow := GetNewWindow( 129, nil, pointer(-1)); 
SetPortCDrawWindow); 


dRect := DrewWindow^.portrect; ( drawing area ) 
drect.left := dRect.left + 46; (make room for palette) 
setRect(r,0,0,576,720); 
OpenBi tMapCr); 
prect := palette^^.picFrame; 
Of fsetRect(prect,-prect.left,-prect. top); 
{ palette bounds } 
DrawPalette; 
end; 


Procedure ChangeTool(NewTool: Integer); ( set a new tool } 
begin 
with LAPwBuf do 
begin 
theType := setToo!; 
tool := NewTool; 
end; 
SendLap(255); 
end; 


Function DoSizeTool(pt:point;r:rect;cur: integer): integer; 
var 


X : integer; 

r2 ‘rect; 
begin 

repeat 


х := (pt.v-r.top) div 2; 
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if xct then 
x := 1 
else if х› 16 then 
x := 16; 
if x©cur then 
begin 
SetRect(r2,r.left,r.toptCcur- 12*2,r .right,r.top*tcur*2); 
InvertRect(r2); 
cur := X; 
SetRect(r2,r.left,r.top*Ccur- 1DD*2,r.right,r. top*cur*2); 
InvertRect(r2); 
end; 
GetMouse(pt); 
until MyGetNextEvent CmUpMask, myEvent); 
DoSizeTool := cur; 


end; 
procedure PatternEditor(VAR myPat:Pattern); 
var 
dig : DialogPtr; 
aPat  : Pattern; 


myEvent : EventRecord; 
done  : Boolean; 

drew : Boolean; 

dh, dv : Integer; 
patRect : Rect; 
petEdit : Rect; 

tRect : Rect; 
savePort : GrafPtr; 


function GetBitRect( index: Integer ):Rect; 
begin 
dh:=Cindex mod 8)*19; 
dv:=Cindex Div 82%10; 
with tRect do 
begin 
lef t:=patEdit.left+dh; 
right:=left+10; 
top :=patEdit. toptdv, 
bottom :=top+ 10; 
end; 
InsetRect(tRect, 1, 1); 
GetBitRect:=tRect; 
end; 


procedure InitPatBits; 

var 

i : Integer; 
begin 

for і:-0 to 63 do 

1f BitTstCeaPat, i) 
then 
FillRectCGetBitRectCi2,Black) 


else 
FillRect(GetBitRect(i), White); 
end; 


function GetBitPos(pt:point): integer; 

begin 
dh:=pt.h-patEdit. left; 
аһ:=аһ div 10; 
dv:=pt.v-patEdit.top; 
dv:=dv div 10; 
GetBitPos:-dv*8*dh; 

end; 


procedure EditPatClick(pt:point;f irstOne:Boolean); 


index : integer; 
begin 
index :=GetBitPos(pt); 
if firstOne then 
begin 
if BitTstC8aPat, index) 
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then begin 


draw:=false SetRect(bm.bounds,0,0,16,16); 
else bm.baseAddr := @theCurs; 
draw:=true; bm.rowButes := 2; 
end; saveBits := drawWindow .portbits; 
if draw SetPortBits(bm); 
then EraseRect(bm.bounds); 
begin with UTI2] do 
FillRect(GetBitRect( index), Black); SetRect(r,0,0,hSize,vSize); 
BitSetC8aPat, index); FillRectCr,black); 
end SetPor tBits(saveBits); 
else SetCursor( theCurs); 
begin end; 
FillRect(GetBitRect( index), White); TSplatter: SetCursor( theSprayer**); 
BitCirC@aPat, index); Tletters: SetCursor(GetCursor( iBeamCursor )**); 
end; Terase: 1f MacII then 
FillRect(patRect, aPat); begin 
end; SetCursor(arrow); ( * For now, manipulate color cursor *) 
end 
begin else 
GetPort(savePort); begin 
aPat:=muPat; SetRect(bm.bounds,0,0,16,16); 
dlg:=GetNewDialog(1000,Nil,Pointer(-1)); bm.baseAddr := @theECurs; 
HiliteButton(dlg); bm.rowBytes := 2; 
done :=false; saveBits := drewWindow^ .portbits; 
GetDItemCd1g,3, iType, item, patEdit); SetPor tBitsCbm); 
tRect:=patEdit; FillRect(bm.bounds, white); 
InsetRect(tRect,-1,-1); with UTI2] do 
FrameRect(tRect); SetRect(r,8,8,hSize,vSize); 
GetDItemCdlg, 4, iType, iTem, patRect); FrameRect(r); 
tRect:=patRect; bm.baseAddr := @theECurs.mask; 
InsetRect(tRect,-1,-1); EraseRect(bm.bounds); 
FrameRect(tRect); FillRect(r, black); 
FillRect(patRect, aPat); SetPortBits(saveBits); 
InitPatBits; SetCursor(theECurs); 
Repeat end; 
CheckQueue ; Trect. .Tfoval: 
If MyGetNextEventCeveryEvent, myEvent ) then Se tCursor(GetCursor (crossCursor )**); 
If isDialogEvent(myEvent) then end; 
if DialogSelect(myEvent, myWindow, itemHit) then updateCurs := false; 
Case itemHit of end; 
Ok, Cance! :Done:=True; 
3: Procedure FixCursor; ( handle cursor updating } 
with myEvent do var 
begin pt :point; 
Global ToLocal (where); begin 
EditPatClick(where, true); If windowPeek(FrontWindow)* .windowKind>-1 then 
Repeat begin 
Ge tMouse (where); GetMouse(pt); 
if PtInRect(where, patEdit) then if (PtInRect(pt,dRect) and arrowCurs) or updateCurs then 
EditPatClick(where, false); begin 
CheckQueue ; SetupCursor ; 
Until Not StillDown; arrowCurs := false; 
end; end 
end; (Case) else if (not PtInRect(pt,dRect)) and (not 
Until done; arrowCurs) then 
if ItemHit=0k then begin 
myPat:=aPat; setCursor (arrow); 
DisposDialog(dlg); arrowCurs := true; 
SetPort(savePort); end; 
end; end; 
end; 
Procedure SetupCursor; 
var Procedure SavePic(saveas:boolean);  ( save file ) 
savebits,bm  :bitmap; var 
r ‘rect; where ‘point; 
begin reply :SFReply; 
with ОТСО) do err : integer; 
case theToo! of ar, dr ‘packed array (0..75] of byte; 
Torush: 1f MacII then n,1 :longint; 
begin i,j,ref : integer; 
SetCursorCarrow); ( * For now, manipulate color cursor * ) r,rr rect; 
end bm :bitmap; 
else srcPtr :ріг; 
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dstPtr :ptr; 
h :handle; 
S :str255; 


procedure ChkErr; 
begin 
if err © 0 then 
DoErrCerr); 
end; 


begin 
if not saved then 
saveas := true; 
if saveas then 
begin 
SetPtCwhere , 50,50); 
GetWTitleCdrawWindow,s); 


SFPutFileCwhere, Save document as:’,s,@idleFilter,reply); 


BeginUpdateCDrawWindow); 
DrawContents; 
DrawPalette; 

EndUpdate(CDrawWindow); 

end 
else 
with reply do 

begin 
good := true; 
GetWTitleCdrawWindow,s); 


fname := S; 
vRefNum := fVref; 
end; 
1f reply.good then 
begin 
err := SetVol(nil,reply.vRefNum); 
ChkErr ; 
if saveas then 
begin 


err := FSDelete(reply.fname,reply.vRefnum); 
if (erro поЕгг) and Cerro fnfErr) then 
ChkErr ; 
err := 
Create(reply.fname,reply.vRefnum, JPNT 2, "PNTG"); 
ChkErr ; 
end; 
err := FSOpen(reply.fname,reply.vrefnum, ref); 
ChkErr ; 
1f saveas then 
begin 
err := SetEOF(ref,512); 
ChkErr ; 
err := SetFPosCref , f sFromStart,9); 
ChkErr ; 
1 := 0; 


n := 4 


err := FSWriteCref,n,@1); (write version 8 0) 


ChkErr ; 
end; 
err := SetFPos(ref, fsFromStart,512); 
ChkErr ; 
with bm do 
begin 
SetRect(bounds, 8,8, 72*8, 1); 
baseAddr := баг, 
rowbytes := /2; 
end; 
SetRectCrr,0,9,576, 1); 
for i := 0 to 719 do 
begin 
setRect(r,0,1,576,i* 12; 
CopyBits(bmap,bm,r,rr,SrcCopy,nil); 
srcPtr := ваг; 
dstPtr := @dr; 
PackBitsCsrcPtr,dstPtr, 72); 
n := ord(dstPtr )-ord(@dr); 
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end; 


err := FSWrite(ref,n,@dr); 
ChkErr ; 
CheckQueue ; 
end; 
err := FSClose(ref 2; 
ChkErr ; 
SetWTitleCdrawWindow,reply.fname); 
fVref := reply.vRefnum; 
changed := false; 
saved := true; 
end; 


Function MySaveProc(d1g:DialogPtr Var 
theEvent :EventRecord;VAR IH: Integer ):Boolean; 
begin 


Se tUpA5 ; 
MySaveProc:=false; 
CheckQueue ; 
RestoreA5; 


end; 


Function Continue:Boolean; 
var 


choice : Integer; 


begin 


Continue:-true; 
If changed then 
begin 
choice:zNoteAlert(2099 , @MySaveProc); 
Case Choice of 
2:begin 
savePic(false); 
If changed then 
Continue :=false; 


end; 


var 


end; 
3: Continue :=false; 
end; 
end; 
Procedure LoadPic; ( load picture ) 
where ‘point; 
reply :SFRep ly; 
err ' integer; 
ar ‘packed array [0..75] of byte; 
n : longint; 
i,j,ref : integer; 
Erb ‘rect; 
bm ‘bitmap; 


srcPtr,p ‘ptr; 
dstPtr :ptr; 
typeList :SFTypeList; 


procedure ChkErr; 


begin 
if err © Ø then 
DoErr(err); 
end; 


begin 


If not Continue then 
exit(LoadPic); 
SetPt(where,80,50); 
tupeList[0] := 'PNTG'; 
SFGetFile(where, ‘Open 


document: ^,nil, 1, typelist, 8 idleFilter,reply2; 


if reply.good then 
begin 
BeginUpdate(DrawWindow); 
DrawContents; 
DrawPalette; 
EndUpdate(DrawWindow); 
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err := SetVol(nil,reply.vRefNum); 

ChkErr ; 

err := FSOpen(reply.fname,reply.vrefnum,ref ); 

ChkErr ; 

err := SetFPosCref,fsFromStart,512); 

ChkErr ; 

with bm do 

begin 

SetRect(bounds, 8,8, 72*8, 1); 
baseAddr := @ar; 
rowbytes 72; 


end; 
err := GetEOFCref,n); 
ChkErr ; 
n := n-512; 
p := NewPtr(n); 
srcPtr := p; 
err := FSRead(ref,n,srcPtr); 
ChkErr ; 
SetRect(rr,8,8,576, 1); 
for i := 0 to 719 do 
begin 
dstPtr :- ваг; 
UnPackBits(srcPtr,dstPtr, 72); 
setRect(r,0,1,576,1* 12; 
CopyBitsCbm,bmap,rr,r,SrcCopy,ni1); 
CheckQueue; 
end; 
disposPtr(p); 
err := FSCloseCref 5; 
ChkErr ; 
SetWTitleCdrawWindow, reply. fname); 
fVref := reply.vRefnum; 
changed := false; 
saved := true; 
InvalRect(drect); 
end; 
end; 


Procedure FadeIn(r:rect;pat:pattern); 
var 
у,һ,х,і,п :longint; 
begin 
pennormal; 
penpat(pat); 
with r do 
begin 
v := bottom-top; 
h := right-left; 
for x := 1 toh do 
begin 
n := (x*v) div h; 
for i := 1 to n do 
begin 
moveto(x*left,top*Ci*v) div n); 
line(0,0); 
end; 
end; 
end; 
end; 


Procedure FadeOut(r:rect;pat:pattern); 
var 
v,h,x,i,n : longint; 
begin 
pennormal; 
penpat(pat); 
with r do 
begin 
v := bottom-top; 
h := right-left; 
for x := 1 toh do 
begin 
n := ((h-x)*v) div h; 
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for i := 1 ton do 

begin 
moveto(x*left,top*Ci*v) div n); 
lineC2,0); 

end; 

end; 
end; 
end; 


Procedure FadeInto(r:rect; inPat,outPat:pattern); 
begin 
SysBeep( 1); 
end; 


Procedure PastePicture; 


var 
PPHd1 : Handle; ( * Paste Picture handle * ) 
PTHd1 : Handle; ( * Paste TEXT handle * ) 
Sclen : Longint; 
offset : Longint; 
anEvent : EventRecord; 
PicRect : Rect; 
err : Longint; 
info : FontInfo; 
TEXTStr : Str255; 
TBox  : Rect; 
begin 


err:-LoadScrap; 
PPHd1:sNewHandleC0); 
Sclen:-GetScrapCPPHdl, PICT” offset); 
If Sclen<® then 
begin 
PTHd] :=NewHandle(@); 
Sclen:=GetScrap(PTHdl, ’TEXT’, offset); 
If Sclen>-1 then 
begin 
GetFontInfoCinfo); 
GetiText(PTHd1, TEXTStr); 
with DrawWindow*.portRect, info do 


SetRectCTBox, left, top, lef t+StringW idth TEXTStr Ж 1, toptascenttdescent* leading); 
HLockCPTHd1); 
РРНа1 :=HandleCOpenPictureCTBox)); 
TextBox (PTHd1*,Sclen, ТВох, teJustLef t2; 
ClosePicture; 
HunLockCPTHd12); 
end; 
DisposHandle(PTHd1); 
end; 
If Sclen>-1 then 
begin 
SetCursor(ThePlacer**); 
Repeat 
CheckQueue ; 
Until MyGetNextEvent (mDownmask , anEvent); 
with anEvent do 
begin 
Global ToLocal (where); 
If Cwhat=mouseDown) & 
(PtinRectCwhere,DrawWindow^.portRect? & not 
(PtInRect(where, prect))) then 
with PicHandle(PPHd1)**.picFrame, where do 
begin 
ClipRect(dRect); 
SetRect(PicRect,h,v,h+Cright-left),v+Cbottom-top)); 
DrawPicture(PicHandleC(PPHd!),PicRect); 
OffBits; 
DrawPicture(PicHandle(PPHd1),PicRect); 
OnBits; 
ClipRect(DrawWindow* .portRect); 
end; 
end; 
updateCurs :=true; 
end; 
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DisposHandle(PPHd1); 
end; 


Procedure ResizeSprauKan; 
var 
ResizeBox : Rect; 
CircleBox : Rect; 


savePort : GrafPtr; 

pt : Point; 

tStr : Str255; 

X,U : Integer; 

newRad : Integer; 

newSpeed : Integer; 

sr : Integer; ( * Save radius * } 


procedure ShowSizeCwhere:Point); 
var 
dx,dy,dd : Integer; 
begin 
with where do 
begin 
dx :=abs(x-h); 
dy :=abs(y-v); 
end; 


dd :=dy; 
If dd«sr then 
EraseRect(ResizeBox); 
sr :=dd; 
Se tRect(CircleBox, x-dd, y-dd, x+dd,y+dd); 
Fill0val(CircleBox, Black); 
newRad :=dd; 
end; 


begin 
GetPort(savePort); 
D1g:-GetNewDialogC 100 1,Nil,Pointer(C- 122; 
HiliteButton(D1g); 
setCursor(theSizer**); 
newRad :=UT(8].splatRad; 
PenNorma] ; 
GetDItemCD1g,5, iType, iTem, Box); 
newSpeed :=UT(0].splatSpeed; 
SetilextCiTem,Str(CnewSpeed)); 
SeliText(D1g,5,8,255); 
GetDItemCD1g,3, iType, iTem, Box); 
ResizeBox : =Box; 
InsetRect(Box,-1,-1); 
FrameRect (Box); 
sr :=newRad; 
with ResizeBox do 
begin 
x:=lefttCright-left) Div 2; 
y:=top+Cbottom-top) Div 2; 
SetRect(CircleBox,x-sr,y-sr,xtsr,ytsr); 
end; 
Fill0val(CircleBox, Black); 
ItemHit:-20; 
Repeat 
CheckQueue; 
If MyGetNextEventCeveryEvent,myEvent) then 
If isDialogEvent(myEvent) then 


if DialogSelect(myEvent,D1g, itemHit) then 


Case itemHit of 
ok: begin 


GetDItemCD1g,5, iType, iTem, Box); 


GetiTextCiTem, tStr); 
newSpeed :=Val(tStr); 
If newSpeed< 1 
then 
begin 


392 


SysBeep( 1); 
newspeed :=1; 
end 
else if newSpeed) 255 then 
begin 
SysBeep( 1); 
newspeed :=255; 
end; 
end; 
3: with myEvent do 
begin 
GlobalToLocal(where); 
pt:=where; 
ShowSize(where); 
Repeat 
GetMouse(where); 


If PtinRect(where,ResizeBox) then 
If longIntCwhere)<> longInt(pt) then 


begin 
ShowSizeCwhere); 
pt:=where; 
end; 
CheckQueue ; 
Until Not StillDown; 
end; 

end; ( case ) 

Until ItemHit in [ok,cancel]; 

If ItemHit=ok then 

begin 
with LAPwbuf do 
begin 
theType := setSplat; 
sRad := newRad; 
sSpeed := newSpeed; 
end; 
SendLAP(255); 
end; 
DisposDialog(D1g); 
SetPort(savePort); 
end; 


Procedure ToolClick(pt:point); 
var 
1,8,h,v : integer; 
db1C lick : boolean; 
where ‘point; 
outColor :R6BColor; 
begin 
dblClick := (TickCount-clickTime«GetDblT ime); 


д 


possible double click? } 


clickTime := TickCount; 
a := 0; 
for i := 1 to 20 do 
if ptInRect(pt, toolRects[i]) then 
begin 
a := i; 
leave; 
end; 
db1Click:=Ca=lastTool) and dblClick; 
if ad then 
begin 
lastTool := а; 
case a of 
1: begin ( spray can } 
with LAPwbuf do 
begin 
theType := paintMode; 
mode := not UTI2]. theMode; 
end; 
SendLAP (255); 
PenMode(PatXOR); 
PenPat(1tgrau); 
PaintRect(toolRects[Tsprau]); 
PenNormal; 
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end; 
2..9: 1f dblClick then 
case a of 
TErase: begin 
LAPwbuf . theType := eraseall; 


SendLAP (255); 
end; 
TSplatter: 
ResizeSprayKan; 
end 
else 


with UT(9] do ( Handle new tools ) 
if theTool<>a then 
begin 
InvertRectCToolRects ( theToo112; 
InvertRectCToolRects(a1); 


СһапдеТоо1(а); 
end; 
10: begin — ( disk icon ) 
end; 


11, 12: 1f CPatternsUp<>(Ca=11)) and MacII then 
( pattern/color switch ) 
begin 
PenModeCPatXOR); 
PenPat(1tgrau); 
PaintRect(toolRects[Tpat]); 
PaintRect(toolRects[Tcolor]); 
РепМогта1; 
PatternsUp := not PatternsUp; 
if PatternsUp then 
DisplayPatterns 
else 
DisplauColors; 
end 
else if PatternsUp<>(a=11) then 
sysbeep( 1); 
13..20: 1f dblClick then 
begin 
1f patternsUp then 
begin 
PetternEditor(thePatterns[a- 121); 
with LAPwbuf do 
begin 
theType := setpat; 
pat := thePatterns[a- 121; 
end; 
SendLAP(255); 
curPat := a-12; 
DisplayPatterns; 
end 
else 
begin 
color picker } 
SetPtCwhere, 9,8); 
color picker will center itself * } 
if GetColor(where, Set Pallete 
color to:’, theColors[a-12],outColor) then 
begin 
theColors[a-12]:=outColor; 
with LAPwbuf do 
begin 
theType := setcolor; 
clr := outColor; 
end; 
SendLAP(255); 
end; 
curColor := a-12; 
DisplayColors; 
end; 
end 
else ( single click } 
begin 


( * The 


if PatternsUp and СсогРаїоа- 12) then 


 ( pattern/color selection ) 
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in 
with LAPwbuf do 
begin 
theType := setpat; 
pat := thePatterns[a- 12]; 
end; 
SendLAP( 255); 


curPat := a-12; 
FillRectCcurPatRect, thePatterns[curPat]); 
end 
else if not(patternsUp) and 
CcurColor<>a-12) then 


begin 
with LAPwbuf do 
begin 
theType := setcolor; 
clr := theColors[a- 12]; 
end; 
SendLAP (255); 


curColor := a-12; 
RGBForeColorCtheColors[IcurColor 1); 
PaintRect(curPatRect); 
end; 
end; 
end; 
updateCurs := true; 
end 
else if PtInRect(pt,hSizeRect) then 
begin 
v := UT[0].vSize; 
h := DoSizeTool(pt,hSizeRect,UT[0].hSize); 
with LAPwbuf do 
begin 
theType := setPen; 
px := h; 
py := v; 
end; 
SendLAP(255); 
updateCurs:=true; 
end 
else if PtInRect(pt,vSizeRect) then 
begin 
h := UT[0].hSize; 
v := DoSizeTool(pt,vSizeRect,UT[0].vSize); 
with LAPwbuf do 
begin 
theType := setPen; 
v; 


`D 
x 
f wu 


end; 
SendLAP(255); 
updateCurs := true; 
end; 
end; 


Function Sgn(i: integer): integer; 
begin 
if 1‹0 then 
sgn := -1 
else if i»? then 
sgn := 1 
else 
sgn := 0; 
end; 


Procedure MakeRect(ptl:point); 
var 
LastPt,pt : point; 
х,у : integer; 
dx , dy : integer; 
r ‘rect; 
begin 
lastPt := ptl; 
with pt! do 
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begin 


X 


у: 
end; 
Repeat 
GetMouse(Pt); 
if pt.h)drect.right then (pin mouse inside drect} 
pt.h := drect.right 
else if pt.h<drect.left then 
pt.h := десі left; 
if pt.v»drect.bottom then 
pt.v := drect.bottom 
else if pt.v<drect.top then 
pt.v := drect.top; 
1f longint(LastPt)<> longint(pt) then ( mouse 
moved ) ( NOTE: this is faster than EqualPt } 
begin 
- erase old rect - ) 
SetRect(r,x,y,LastPt.h,LastPt.v); 
if x»LastPt.h then 


h; 
v; 


begin 
r.left := LastPt.h; 
r.right := x; 
end; 
if yLastPt.v then 
begin 
r.top := LastPt.v; 
r.bottom := y; 
end; 


CopyBits(bmap,Wbits,r,r,srcCopy,nil); ( 
flicker-matic quick fix ) 
( - check for shift constraint - ) 
1f bitAnd(mods, shif tKey2) O0 then 
begin 
dx := abs(pt.h-pt1.h); 
dy := abs(pt.v-ptl.v); 
1f dy<dx then 
pt.h := ptl.h + dy*sgn(Cpt.h-pt1.h) 
else 
pt.v := pti.v + dx*sgn(pt.v-pt1.v2; 
end; 
( - calculate new rect - } 
SetRect(r,x,y,pt.h,pt.v); 
if »pt.h then 


r.right := x; 


end; 
і? ypt.v then 
begin 
r.top := pt.v; 
r.bottom := y; 
end; 
( - fix mistakes - ) 
with UT[0] do 
( set mu user state cuz checkqueue screws it up ) 
begin 
PenPat(thePat); 
if MacII then 
Re6BForeColor(CtheClr2; 
PenSizeChSize,vS ize); 
end; 
( - draw rect - ) 
case UTI2).theToo! of 
TRect: begin 
if bitAndCmods, optionKey)=0 then 
PenPat(black); 
FrameRect(r); 
end; 
TFRect: begin 
PaintRect(r); 
1f bitAnd(mods,optionKeu)=0 then 
begin 
PenPat(b lack); 
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FrameRect(r); 
end; 
end; 
Т0уа1: begin 
1f bitAnd(mods, optionKey)=8 then 
PenPat(black); 
FrameOval(r); 


end; 
TFOval: begin 
PaintOval(r); 
1f bitAnd(mods, optionKey)=2 then 
begin 
PenPat(black); 
FrameOval(r); 
end; 
end; 
end; 
end; 
LastPt := pt; 
CheckQueue; 
Until MyGetNextEvent(mupmask, myEvent); 
with LAPwbuf do 


begin 
theType := rectpck; ( send rectpck packet } 
rct := r; 
optDown := (bitAnd(mods, opt ionKey)<>8); 
end; 
SendLAP(255); ( send message to everyone } 
end; 
Procedure MasterClick(pt:Point); (mouseDown our window) 
var 
LastPt ‘Point; 
dx, dy : integer; 
mypart : integer; 
begin 


* [f a DA then get of of here * ) 
1f windowPeekCFrontWindow2^ .windowKind<@ then 
exit(MasterClick); 
if PtInRect(pt,prect) then ( click in palette } 
ToolClickCpt) 
else 
begin 
if UTI2].theTool in ([TRect..TFOval] then 
MakeRect(pt) 
else 
begin 
with LAPwbuf do 
begin 
theType := ѕеїроѕ; ( send setpos packet ) 
mx := pt.h; 
my := pt.v; 


end; 
SendLAP(255); (send setpos packet to everyone} 
Repeat 
GetMouse(Pt); 
if pt.rodrect.right then ( pin 
mouse inside drect ) 
pt.h := drect.right 
else if pt.h<drect. left then 
pt.h := drect.left; 
if pt.v»drect.bottom then 
pt.v := drect.bottom 
else if pt.v«drect.top then 
pt.v := drect.top; 
if Clongint(LastPt)© longint(Pt)) | 
CUT[®@].TheTool=Tsplatter) then ( mouse moved ) ( NOTE: this 
is faster than EqualPt ) 


begin 
with LAPwbuf do 


drag; (send drag packet) 
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end; 
SendLAP(255); (send message to everyone) 


LastPt := Pt; 
end; 
CheckQueue; 
Until MuGetNextEvent(mupmask,muevent); 
end; 
end; 


end; 


Procedure MasterKeyCtheChar : char); 
begin 
1f UT(®@].theTool = Tletters then 
1f theChar>=’ ' then 
begin 
with LAPwbuf do 
begin 
theType := alpha; 
ch := theChar; 
end; 
SendLAP(255); 
end; 
end; 


Procedure ChangeFont; 


var 
S :str255; 
i : integer; 
begin 


CheckItemCmyMenus Lf ontMenu], theFontidx, false); 
theFontidx:-theItem; 
GetI temCmymenus[fontMenu], theItem, s); 
GetFNumCs, theItem?; 
CheckItem(myMenus [ f ontMenu 1, theFont idx, true); 
with UT[0] do 
if theItemo theFNum then 
begin 
with LAPwbuf do 
begin 
theType := setfont; 
fnum := theltem; 
fsize := theFSize; 
fstyl := theFstyle; 
end; 
SendLAP(255); 
end; 
for i:=1 to 9 do 
begin 
Get ІћетстуМепиѕ (5 і 2еМепи], 1,5); 
if RealFont(theltem,Val(s)) 
then 
SetItemStule(muMenus[sizeMenu),i,[O0utline]) 


18е 
SetItemStyle(myMenus[sizeMenul, i, (12; 


end; 
end, 
procedure ChangeStyle; 
const 
plainitem = 1; 
var 


markChar :сһаг; 
StyleArray :packed array [1..7) of styleitem; 
i : integer; 
CStyle  :style; 

begin 
CStyle:-UT[2).theFStyle; 
StyleArrayl1]:=Bold; 
StyleArray[2]:=Italic; 
StyleArray(3] :=Under 1 ine; 
StyleArray[4]:=Outline; 
StyleArray[5] :=Shadow; 
StyleArray[6] :=Extend; 
StyleArray(71]:=Condense; 
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If theitem-plainItem then 
begin 
CheckItem(nyMenus [styleMenu], 1, true); 
for i:-2 to 8 do 
CheckI temCmyMenus[styleMenu], i, false); 
CStyle:=[]; 
end 
else 
begin 
CheckItemCnyMenus[styleMenul, 1, false); 
GetItemMarkCmyMenus [styleMenu], thei tem, markChar ); 
If markChar=chr CnoMark) then 
begin 
CStyle:=CStyle+(StyleArrayl thei tem-1]]; 
CheckI temCmyMenus [styleMenu], theitem, True); 
end 
else 
begin 
CheckI temCmyMenus [styleMenu], theitem, false); 
CStyle:=CStyle-(StyleArrayltheitem-1]]; 
If CStyle={] then 
CheckI temCmyMenus[styleMenu], 1, true); 
end; 
end; 
if CStyleo UTI]. theFStyle then 
begin 
with LAPwbuf do 
begin 
theType := setfont; 
with UT(2] do 


begin 
fNum := theFNum; 
fSize := theFSize, 
fStyl := CStyle; 
end; 
end; 
SendLAP C255); 
end; 
end, 
Procedure ChangeS ize; 
var 
S :str255; 
begin 
if theSizeidxo theItem then 
begin 
CheckItemC(myMenus [sizeMenu], theSizeidx, false); 
Check! tem(myMenus[sizeMenu], theItem, true); 
theSizeidx:=theltem; 
бе temCmymenus(sizeMenu], {ће tem,s); 
іһе tem:=Val(s); 
with UTIS] do 
begin 
with LAPwbuf do 
begin 
theType := setfont; 
fnum := theFNum; 
fsize := theItem; 
fstyl := theFstyle; 
end; 
SendLAP (255); 
end; 
end; 
end; 
Procedure DrawContents; ( redraw drawing ) 
begin 
SetPortCDrawWindow?; 


CopyBitsCbmap,wbits, drect, drect, SrcCopy,Nil); 
end; 
Procedure PrintPic; ( print a document } 
var 
GetOutEh — : Boolean; 
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temphPrint : THPrint; 


err : OSErr; 

savePort : GrafPtr; 

myPrPort : TPPrPort; 

myS tRec : TPrStatus; 

i : Integer; 
begin 


temphPr int :=hPr int; 
err :=HandToHandChandle( temphPr int)); 
1f ErróNoErr then 
begin 
SysBeep( 1); 
exit(PrintPic); 
end; 
PrOpen; 
1f PrJobDialogCtemphPr int) 
then 
begin 
GetOutEh: false; 
DisposHandleChandleChPr int); 
If MemError<>NoErr then 
SysBeep( 1); 
hPrint:stemphPr int; 
err :=HandToHandChandleChPr int 2); 
If Егг ОМОЕгг then 
begin 
SysBeep( 1); 
GetOutEh:=true; 
end; 
end 
else 
GetOutEh :=true; 
PrClose; 
DisposHandleChandleCtemphPr int )); 
1f GetOutEh then 
exit(PrintPic); 
BeginUpdate(DrawW indow); 
DrawContents; 
DrawPalette; 
EndUpdeteCDrawW indow); 
GetPort(savePort); 
for i:=1 to hPrint^^.PrJob. iCopies do 
begin 
PrOpen; 
If PrError=noErr then 
begin 
myPrPor t :=PrOpenDoc(hPrint,Nil,Nil); 
If РгЕггог=поЕгг then 
begin 
PrOpenPageCmyPrPort,Nil); 
If PrError=noErr then 


CopyBi tsComap, myPrPort* .gPort .por tBi ts, bmap . bounds, Отар . bounds , SreCopy Ni; 


PrClosePage(myPrPort); 
end; 
end; 
If РгЕггог-поЕгг then 
PrCloseDoc(myPrPort); 


If KhPrint^^.prJob.bjDocLoop-bSpoolLoop) and 


(PrErrorzNoErr) then 
PrPicFileChPrint, Nil, Nil,Nil,mgStRec); 
PrClose; 
end; 
SetPort(savePort); 
end; 


Procedure DoMyUpdate; 

var 
savePort — :grafPtr, 
tempWindow :windowPtr; 

begin 
tempWindow:-2WindowPtr(myEvent . message); 
GetPortCsavePor t); 
Se tPor t( tempW indow); 
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BeginUpdate( tempWindow); 
if tempWindow=DrawWindow then 
begin 
DrawContents; 
DrawPalette; 
end; 
EndUpdate( tempW indow); 
SetPort(savePort); 
end; 


Procedure DoJamAbout; 
const 
picID = 999; 
var 
AboutWindow: WindowPtr; 
AboutPict : PicHandle; 
AboutRect : Rect; 
AboutEvent : Eventrecord; 
SavePort : GrafPtr; 
x1,y1,x2,y2: Integer; 
begin 
GetPort(SavePort); 
AboutPict:zPicHandleCGetResource(C'PICT^,999)); 
RsrcErr; 
with ScreenBits.Bounds do 
begin 
x1:=right-left; 
yl:=bottom-top; 
end; 
with AboutPict^^.picFrame do 
begin 
x2:=right-left; 
y2:=bottom-top; 
end; 
SetRectCAboutRect, 1, 1,x2,y2); 


AboutW indow : =NewWindow(Nil, AboutRect, ’’, false, 1,Pointer(- 
1), false, ø); 
MoveW indowCAboutW indow, (x 1-x2) Div 2,(y1-y2) Div 2, true); 
ShowWindow(AboutWindow); 
SetPort(AboutWindow); 
with AboutPict^^.picFrame do 
SetRectCAboutRect,8,8,right-left,bottom-top); 
DrawPictureCAboutP ict, AboutRect); 
Repeat 
CheckQueue ; 
Until 
MyGe tNex tEvent(mdownMask+keyDownMask+AutoKeyMask , AboutEvent); 
ReleaseResourceChandle(CAboutP ict 22; 
RsrcErr; 
DisposeWindowCAboutWindow); 
SetPort(SavePort?); 
end; 


Procedure DoCommand(mResult:longint); (menu commands) 
var 
name : Str255; 
begin 
theMenu := HiWord(mResult); 
theItem := LoWord(mResult); 
if BitAnd(myEvent.modifiers,CmdKey) © Ø then 
HiliteMenu(theMenu); 
case theMenu of 
255: If theltem © 1 then 
begin 
GetI temCmyMenus [app leMenu], theI tem, name); 
refnum:=QpenDeskAcc(name); 
end 
else If WindowPeek(FrontWindow)* .windowKind > Ø then 
DoJamAbout 
else 
SysBeep( 1); 
256: case theItem of ( main menu ) 
1: LoadPic; 
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2: SavePic(false); 
3: SavePic(true); 
5: DoPageSetUp; 
6: — 
8: If Continue then 
doneFlag:=true; 
19:begin 
PrDebug := not PrDebug; 
if PrDebug then 
begin 
PrCtlCallCiPrDevCt1,$00010000,92,0); 
debug('— Debug transcript follows’); 
end; 
end; 
end; 
257: ChangeFont ; 
258: ChangeS ize; 
259: ChangeStyle; 
260: case theItem of 
1: FadeInCdrawWindow^ .portRect, UTI]. thePat); 
2: FadeOutCdrewWindow^ .portRect,UTI2) . thePat); 
3: FadeIntoCdrawWindow^ .portRect, black, white); 


end; 
end; 
HiliteMenu(d); 
end; 


Procedure InitTables; ( initialize User Table, Queue ) 


var 
i : integer; 
begin 
with PQ do ( empty queue ) 
begin 
head := 0; 
tail := Ø; 
end; 
with /ТІ01 do 
begin 
id := myNode; 
theTool :- dTool; ( default tool } 
theMode := dMode; ( default mode } 
thePat := black; ( default pattern ) 
theClr := theColors[dColor]; ( default to black ) 
hSize := dPen; ( default pensize ) 
vSize := dPen; ( default pensize ) 
theFnum := applFont; ( default text font ) 
theFsize := dSize; ( default text size ) 
theFstyle := dStyle; ( default text style ) 
x :- 100; ( somewhere оп the screen ) 
y := 50; 
splatSpeed := dsplatterCount;( default speed ) 
splatRad := dsplatRad; ( default radius ) 
( time needs no initialization ) 
end; 
for i := 1 to maxUsers do 
begin 
UTLI] := UT[0]; 
UTLil.id := -1; ( invalidate all users } 
end; 
end; 


Procedure ReadPatCol; (read patterns & colors into memory) 
var 
RGBColors :CHandle; 
1 : integer; 
begin 
for i:=1 to 8 do 
GetIndPatternCthePatterns[i], 128,1); 
RGBColors :=CHandle(GetResource( 'CLRS ^, 128)); 
RsrcErr; 
theColors :=RGBColors** ; 
ReleaseResourceChandleCRGBColors22; 
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RsrcErr; 
end; 


Procedure InitGlob; 
const 
UnImplTrepNum = $9F; 
WaitNextEventTrapWord 
var 
i,j : integer; 
Rom,Machine  :integer; 
theWor ld :SysEnvRec; 
begin 
* Get the world, so to speak * ) 
if SysEnvirons( 1, theWor 1d) O envNotPresent then 
begin 
MultiFinderRunning:2CtheWorld.machineType?20) & 
(NGetTrepidchess(Wsi tNextEvent Traphiord, Too T Trap X>NGet TrepAdchess(Uh Tp Trem, Tool Trep)); 
ColorQDrawImp1m:=theWor 1d.hasColor QD; 
end 
else 
begin 
MultiF inderRunning:=false; 
ColorQDrawImplm:-false; 
end; 
Environs(CRom, Machine); 
1f Machine=2 
then 
MacII:=true 
else 
MacII:-false; 
PixDraw:=false; 
( * Controls if mac II pix map is working or not * } 
MacII:-false; 
PrDrvrOpen; 
PrDebug := false; ( *** for debugging onlu *** ) 
err := MPPOpen; ( open Appletalk driver ) 
if егг ОпоЕгг then 
begin 
SysBeep( 1); 
exitToShell; 
end; 
err := GetNodeAddress(muNode,muNet);( who am I? ) 
if еггОпоЕгг then 
begin 
SysBeep( 1); 
exitToShell; 
end; 
err := LapOpenProtocol(OurType,nil); ( open our 
protocol type ) 
if err ónoErr then 
begin 
sysBeep( 1); 
exitToShel1; 
end; 
LAPrh := ABRecHandle(newHandle(lapSize)); { handle for 
LAP reads } 
LAPwh := ABRecHandle(newHandle(lapSize)); { handle for 
LAP writes } 
HLockChandleCLAPrh)); 
HLockChandleCLAPwh2); 
hPr int :=THPr int CNewHandleCSizeOf CTPr int 222; 


( init globals, user table, etc. ) 


( * Unimplemented trap * ) 
- $60; 


SetUpRead; ( set up initial LAPRead ) 
palette :- PicHandle(GetResource( ‘PICT’, 10002); 
RsrcErr; 
jamPic :- PicHandle(GetResource( ‘PICT’, 10012); 
RsrcErr; 
for i := 1 to 20 do 

begin 


j := Ci-1) div 2; 

if oddCi) then 
SetRectCToolRects[i1,0,20*3,22,20*C(j* 10- 1) 

else 

SetRectCToolRects[i1,23,20*3,45,20*C jt D- D; 

end; 
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SetRect(curPatRect,3,203,42,225); 

SetRect(hSizeRect,0,231,21,266); 

SetRect(vSizeRect,23,231,44,266); 

PatternsUp := true; 

curPat := 1; 

curColor := 

ReadPatCol; 

PatternsUp :=true; 

for i := 0 to 15 do 
theCurs.mask[i] := 8; 

setPtCtheCurs .hotspot,2,0); 

setPtCtheECurs .hotspot,90,0); 


1; 


arrowCurs := true; 

updateCurs := false; 

InitTables; 

OpenDrawWindow; 

textMode(CSrcCopu?; 

clickTime := Ø;  ( set up doubleclick variables ) 
lastTool := -1; 

DoneFlag := false; 


theSizeidx := 3; 

changed := false; 

theSizer :=GetCursor( 1000); 

theHand :=GetCursor( 1001); 

theP lacer :=GetCursor( 1002); 

theSprayer :=GetCursor ( 1003); 
end; 


Procedure CleanUp; 


Repeat 
FixCursor ; 
CheckQueue; ( something for us to do while we idle ) 
17 MyGetNextEventCeveryEvent, nyEvent ) then 
with myEvent do 
case what of 


mouseDown : 
begin 
mods := modifiers; 
code := FindWindow(where, tempWindow); 


case code of 
inMenuBar: DoCommand(MenuSelect(where)); 
InSysWindow: SystemClick(myEvent, tempWindow); 
inContent, InDrag: 
1f tempWindow © frontWindow then 
begin 
SelectWindowCtempWindow); 
SetPortCtempWindow); 
end 
else if FrontWindow=DrawWindow then 
begin 
GlobalToLocal(where); 
MasterClick(where); 
end; 
end; 
end; 
keuDown, autoKeu: 
begin 
theChar := chr(BitAnd(message,255)); 


( All of this isn’t really necessary except for closing our 1f BitAndCmodifiers, CmdKey)<>8 then 


protocol type. The application heap will be flushed anyway, begin 
but we ought to set a good exemple....) if theChar in [‘v’,’V’] then 
begin PastePicture 
PrÜrvrClose; else 
if LAPrh**.abResult=1 then(stop LAP read if in on) DoCommand(MenuKey( theChar 2) 
begin end 
err := LAPRdCancel(LAPrh); else 
DoErr( 1004); MasterKey( theChar ); 
end; end; 
1f not polling then updateEvt: 
begin DoMyUpdate ; 
err := VRemove(@myTask); ( remove VBLTask } activateEvt: 
DoErr( 1005); if OddCmodifiers) then 
end, begin 
err := LAPCloseProtocol(OurType); (!! close protocol !!) tempWindow:-WindowPtr(message); 
DoErr( 1000); SetPor t( tempW indow); 
err := MPPClose; ( close AppleTalk driver } If tempWindow=DrawWindow then 
DoErr( 1002); begin 


DisposHendleChandleCLAPrh)); 
DisposHandleChandleCLAPwh2); 
releaseResource(Chandle(Cpalette)); 


updateCurs:-true; 
( * Remove Edit menu/ we don't use it, but DAs might * ) 
If FileMenuPresent then 


RsrcErr; begin 
releaseResource(Chandle(jamPic)); FileMenuPresent : "false; 
RsrcErr; DeleteMenu(261); 
1f PixDraw DrawMenuBar ; 
then end; 
begin end 
end else 
else SetCursor Carrow); 
DisposP tr (bmap.baseAddr ); end 
end; else 
begin 


procedure —DataInit;EXTERNAL; 
begin 
UnloadSeg(@_DataInit); (х Get rid of MPW’s init code *) 


( * If our about caused it then give them an Edit menu * ) 


1f CWindowPtr (message )=DrawWindow) & (not 


FileMenuPresent) & (windowPeekCFrontWindow2^ .windowK ind«0) 


FlushEventsCevergEvent 9); then 
InitGraf CéthePort); begin 
InitFonts; FileMenuPresent:-true; 
TEInit; InsertMenuCmyMenus [Edi tMenu], 257); 
InitWindows; DrawMenuBar ; 
InitDialogs(Nil); end; 
InitCursor ; end; 
Se tUpMenus ; end; 
InitGlob; Until donef lag; 
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CleanUp; ( (112, 32, 132, 92), 


SetCursor(GetCursor(WatchCursor) 1“); Button (enabled, "Discard"), 
end. (72, 32, 92, 92), 
Button (enabled, Save"), 
Listing: JamPaint.r (72, 136, 92, 196), 
/* resources for JamPaint.p */ Button (enabled, "Cancel^), 
Type ‘UpNT’ as ‘STR °; (24, 96, 40, 200), 
resource ‘JpNT’ (Ø) (*JemPaint by Edgar Circenis and Rod StaticText (disabled, “Save changes?^))); 
Magnuson - Dec 28, 1987”); resource ‘DLOG’ (1000, "Pattern Editor”) ( 
resource ‘FREF’ (128) ('APPL', 0, ""); (78, 148, 208, 374), 
resource 'BNDL^ (128) ( dBoxProc, visible, noGoAway, хб, 1000 , ^^) ; 
‘JPNT’, Ø, ('ICNt^, (0, 128); "FREF', (0, 128))); resource 'DITL^ C1090) ( 
resource ‘MENU’ (255, “Apple”, preload) ( ( (104, 152, 124, 212), 
255, textMenuProc, Ox7FFFFFD, enabled, apple, Button (enabled, “0k”}, 
( "About JamPaint”, noIcon, *", "^", plain, (104, 80, 124, 149), 
*-*", noIcon, ““, ““ plain)); Button (enabled, Cancel"), 
resource ‘MENU’ (256, “File”, preloadX( (B, 24, 88, 104), 

256, Ø, Ox7FFFFFB7, enabled, "File", UserItem (enabled), 

( "Open.",noicon, “0”, nomark, plain; (8, 128, 88, 208),UserItem (disabled))); 
*Save^,noicon, "S^, nomark, plain; resource ‘DLOG’ (1001, "Resize Spray Kan”) ( 
“Save as..”,noicon, noKey, nomark, plain; (46, 98, 266, 410), 

*-",noicon, noKey, nomark, plain; dBoxProc,visible,noGoAway, 0х0, 19001, ^") ; 
“Page Setup..”,noicon, nokey, nomark, plain; resource 'DITL^ (1001, “Resize Spray Kan”) ( 
“Print..”,noicon, "P^, nomark, plain; ( (176, 232, 196, 292), 
"-% noicon, noKey, nomark, plain; Button (enabled, "OK^), 
*Quit",noicon, "Q^, nomark, plain)); (144, 232, 164, 292), 
resource ‘MENU’ (257, "Font", preload)( Button (enabled, "Cancel^), 
257, 0, OxTFFFFFFF, enabled, “Font”, ()); (16, 16, 208, 208), 
resource 'MENU^ (258, "Size", preload) ( UserItem (enabled), 
258, textMenuProc, al Enabled, enabled, "Size", (40, 224, 56, 296), 
( StaticText (disabled, “Flow Rate"), 
"9" nolcon, "^, "", plain, (70, 234, 84, 288), 
“10”, noIcon, 4”, *", plain, EditText (enabled,^^))); 
“12”, noIcon, "^, check, plain, resource 'DLOG^ (1002, “Printing Error!) ( 
“14”, noIcon, *", ““ plain, (36, 108, 80, 392), 
*18^, noIcon, "", *", plain, dBoxProc, visible, noGoAway, 0х0, 1002 , "^) ; 
^24", nolcon, 4”, *", plain, resource ‘DITL’ (1002, "Printing Error!”) ( 
“36”, noIcon, *", *", plain, ( (18, 37, 29, 253), 
"48", noIcon, “Z, *", plain StaticText (disabled,"An error while printing oc- 
"12", nolcon, 7%; «^ plain)); cured! ^))); 
resource ‘MENU’ (259, “Style”, preload) ( data ‘CLRS’ (128, "colors^, preload) ( 
259, textMenuProc, allEnabled,enabled, “Style”, %%0000 0000 0000" /* BLACK */ 
( $^FFFF FFFF FFFF^ — /* WHITE */ 
“Plain”, noIcon, “”, check, plain, $"FFFF 0000 0000" /% RED */ 
“Bold”, noIcon, “В”, *^, 1, $"0000 FFFF 0000" /* GREEN */ 
“Italic”, noIcon, "I^, *^, 2, %”0000 0000 FFFF^ /* BLUE */ 
"Underline", noIcon, "U^, "", 4, $^FFFF FFFF 0000" /х YELLOW */ 
“Outline”, nolcon, "^, “* 8, $^0000 FFFF FFFF^ /* TURQUOISE */ 
“Shadow”, noIcon, ^^”, “”, 16, $“FFFF 0000 FFFF^ /% MAGENTA */ 
“Extend”, noIcon, *", *", 64, ); 
“Condense”, nolcon, *", ““ 32)); resource ‘PAT#’ (128,"Patterns", preload) ( 
resource ‘MENU’ (260, "Effects", preload) ( 
260, textMenuProc,allEnabled,enabled, "Effects", /* [Black] */ 
( "Fade In^,noicon, noKey, nomark, plain; $^FFFF FFFF FFFF FFFF", 
“Fade Out^,noicon, noKey, nomark, plain; /* [Dk Gray) */ 
“Fade from/to”, noicon, поКеу, nomark, plain)); $"DOFF 77FF DOFF 77FF", 
\resource ‘MENU’ (261, “Edit”, preload) ( /* (Med Gray] */ 
261, textMenuProc, Ox TFFFFFFC, enabled, “Edit”, %“0077 0077 0077 0077", 
( “Can't Undo”, noIcon, “Z?, "", plain, /* [Grau] */ 
*-^ по[соп, "", *", plain, %”АА55 АА55 AA55 АА55", 
“Cut”, noIcon, "X^, "^", plain, /* (White) */ 
“Сору”, nolcon, "C^, **, plain, $^0000 0000 0000 0000", 
“Paste”, noIcon, "V^, "”, plain /* [Spot White] */ 
“Clear”, nolIcon, **, *^, plain); $^8000 0800 8000 0800", 
resource ‘WIND’ (129, “Paint Window", preload) ( /* [More Spots White] */ 
(39, 10,341,502) , %”8800 2200 8800 2200", 
noGrowDocProc, visible, nogoaway, 8x0, "Untitled^;); /* [Still More Spots White] */ 
resource ‘ALRT’ (2000) ( %”8822 8822 8822 8822", 
(78, 122, 234, 364),2000, /* (And Still More Spots White] */ 
( Cancel, visible, sound], $"AA00 АА00 AADO AADO" 
Cancel, visible, soundi, ) 
Cancel, visible, sound], ); 
Cancel, visible, soundl)); include "JamPaint.rsrc^; /* additional resources */ 
resource 'DITL^ (2000) ( include “JamPaint.code’; 
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ABC's of Macintosh 
A Window Menu 


The Standard Window Menu 

A Macintosh program with several windows really ought to 
have a Window menu. This menu is a list of all open application 
windows; choosing a window from the menu brings it to the 
front. 

The problem for the programmer is menu maintenance. 
Every time the program opens a new window, the window's 
name has to be added to the Window menu, and, what is worse, 
every time a window is closed, its name must be removed from 
the menu. There is по ROM trap to delete a menu item in the 64K 
ROM. 

Still uglier problems arise if the menu is supposed to be kept 
in order. Every time a window is selected, the window order 
changes, and the menu must be re-ordered. 

One solution: each time the menu must be updated, delete 
the whole menu and recreate it from the window list. That isn't 
very pretty, but it would work. 

The solution I present here is similar butless work: Draw the 
menu with an MDEF that reads the window list. This approach 
requires virtually no menu maintenance (only a call to 
CalcMenuSize when a window is opened or closed). As an extra, 
the menu includes a “Zoom Front Window" item. 


Advertisement 
This is my third article for MacTutor, and I've got a fourth 
and a fifth in the works. Maybe I'm becoming a regular? 
Anyway, I thought I might mention ways to respond to my stuff. 
The cheapest way is by mail: 
Clifford Story 
Attic Software 
P.O. Box 219 
Goleta, California 93116 
The fastest way is by modem. I run a BBS called THE 
ATTIC, phone number (805) 683-0322, hours 6:00 PM to 2:00 
AM, Pacific time, daily. The board isn't very active, but I read 
and respond each morning. 


ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
я Window.make 
# MPW make file for 
8 dynamic Window menu demo 
® (c) 1988, by Clifford Story 
& Attic Software 


ЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
8 Compile the resources 
ҢЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Window ff Window.make Window.r 

Rez Window.r -append -o Window 
ЖЖ=ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


# Compile common declarations 
ПЖЖЖЖЖАЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
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= Clifford Story 
Goleta, CA 
Volume 5, Number 7 


Pascal 


Common.p.o ff Window.make Common .p 
Pascal Common. 
SRKKKKKKKKKEKKAKKAKKKAKAKAKAKKKKKKKKKKKKKKKKKKX 


® Compile and link the MDEF 
L2$2922929292999999922999999929999999929229992 9: 
'Window Menu'.p.o f Window.make à 
‘Window Menu’.p Common.p.o 
Pascal ‘Window Menu’ .p 
Window ff Window.make ‘Window Menu’.p.o 
Link -m MENUDEF -w -t ‘APPL’ à 
-c '?)9?! 9 -rt MDEF=1001 д 
-sn Main-'Window Menu’ д 
‘Window Menu’.p.o д 
* (Libraries)"Interface.o 9 
* (Libraries) "Runtime.o à 
* (PLibraries)^PasLib.o à 
* (PLibraries) "SANEL ib.o à 
-0 Window 
f Xo x x0 CCcXoooXoooocoooooorecoooereooeotoooeooeeoex 


8 Compile and link the main program 
L2299992999999999999299992999 999999 9099929: 
Window.p.o f Window.make à 
Window.p Common.p.o 
Pascal Window.p 
Window ff Window.make Window.p.o 
Link -w -t APPL -c ‘7777’ д 
Window.p.o à 
* (Libraries)"Interface.o à 
* (Libreries)"Runtime.o à 
* (PLibraeries)"PesLib.o д 
* (PLibraries)"SANELib.o à 


-o Window 
MKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKX 


The Program’s Resources 
The only feature that needs to be pointed out is the declara- 
tion of the Window menu. The “Zoom Front Window” item must 
be declared here, so MenuKey will be able to find its keyboard 
equivalent. 


ТЫ x xxx EAA ARERR AAA EAA EERE EEE 


Window.r 
Resources for 
dynamic Window menu demo. 
(c) 1988, by Clifford Story 
& Attic Software 


XXXX2XXXX55XXXXXXXXXXXXXXXXXXXXXXXXXXXXXK / 


®include “types.r’” 
/*®^®ЖЖЖЖЖЖЖЖЖЖЖХЖЖХЖЖЖЖЖАЖЖЖЖЖЖЖАЖЖЖЖАЖЖЖЖЖЖЖЖ 


Menu resources: 
KERKAAAAA RAK K ALAA AERA AKER ARERR EKER ХХХ / 
resource ‘MENU’ С 1001) ( 
1001, 
textMenuProc, 
$7FFFFFFB, 
enabled, 
apple, 
( /* array: 3 elements */ 
/* (1) */ 
"About Window...^, noicon, 
"v «и plain, 
/* [2) */ 


@ The Best of MacTutor, Vol. 5 


“About Attic Soft- 


ware...”, 


noicon, “*, "^ 


plain, 


/* [3] */ 
=T Rolcon, *^ ЖЕ, 


plain 


); 


resource ‘MENU’ (1002, 


preload) ( 
1002, 


textMenuProc, 


0x7FFFFFFB, 


enabled, 
“File”, 


( /* array: 4 elements */ 
/* (1) */ 
“New”, noIcon, “№, "^ 


plain, 


/* [2] */ 
“Close”, noIcon, "K^, 


*^, plain, 


/* [3] */ 
*-^, nolcon, жс, 


р1аїп, 


/* [4] */ 
“Quit”, nolcon, "Q^, *", 


plain 
) 


); 


resource ‘MENU’ (1003, 


preload) ( 
1003, 


textMenuProc, 


0x7FFFFFFD, 


enabled, 
“Edit”, 


( /* array: 6 elements */ 
/* (1) */ 
“Undo”, nolcon, "Z^, *", 


plain, 


/* [2] */ 
^et nolcon, # 1% 


plain, 


/* (3) */ 


д 


“Cut”, nolcon, "X^, *", 


plain, 


/* [4] */ 
*Copy^, noIcon, "C^, *", 


plain, 


/* [5] */ 
“Paste”, noIcon, "V", 


^^, plain, 


/* [6] */ 
“Clear”, noIcon, *", *", 


plain 


); 


resource ‘MENU’ (1004, 


preload) ( 
1004, 
100 1, 


Ox7FFFFFFC, 


enabled, 


“Window”, 

( /* array: 2 elements */ 
/* [1] */ 
“Zoom Front Window”, 


nolcon, 


ым 
/* [2] */ 
To  nolcon, 4*4. 7%, 


plain 


“” plain, 


); 


) 


/YKXXXX1XXXXXXXXXKXXXXXKXKX 


“About”, 


T; t, 
$^1101 
$^0100 
$3201 
$"0000 
$^ 1844 
$"01EF 
$^^100 
$"0002 
$^FFFD 
%”А000 
%”0А28 
$72031 
$2043 
$"6420 
$^616E 
$^6329 
$°7477 
$"2E4F 
$^3231 
%”6574 
$^ 1161 
$^6961 
$^3136 
$A 100 
$0002 
$"004C 
%”А000 
%”5200 
$“6F77 
$°7374 
$*6 120 
$6320 
$^ 106Е 
$"2E20 
$^1469 
$^696E 
$ *99А1 
$0000 
$”9828 
$^1320 
%”206Ғ 
$^6564 
$^6865 
$7729 
$6572 
$6573 
%”6065 
%”А000 
$"002C 
%”А000 
%%2261 
%”6963 
%%7064 
$^6F20 
%%7420 
$^206E 
$^646F 
$^122C 
$^7468 
$"009A 
$0008 
$0082 
$2077 


306, 
A000 
0А00 
F 10A 
0000 
0009 
0700 
9600 
03А1 
0000 
9803 
0128 
3938 
6C69 
5374 
6420 
AC22 
6172 
2E20 
392С 
612С 
6С69 
2020 
A000 
9600 
03A1 
0000 
9800 
2222 
2064 
7261 
6479 
5769 
7120 
2045 
6065 
646Ғ 
000A 
0008 
0062 
6F70 
7220 
2020 
2077 
D8 1C 
2063 
2020 
6E75 
99A1 
0000 
9828 
7574 
616C 
6174 
7265 
7429 
6577 
7720 
2077 
6500 
0008 
0000 
0022 
696E 


Picture resources 
XXXKKKKKKKKKKKKKKKKKKKKK CK ЖКК ЖКК ЖЖЖ / 


resource ‘PICT’ (1001, 
purgeable) (1157, 


497), 

8240 008С” 
0700 0701" 
0000 0000" 
0800 1800" 
0009 0130" 
0200 0248" 
0606 0000" 
009A 0008" 
0004 0000" 
0003 0000" 
0024 2249" 
3820 6279" 
6666 6Ғ72" 
6F72 7920" 
4174 7469" 
2053 6Ғ66" 
652C 2050" 
426F 7820" 
2047 6Ғ6С” 
2043 2946" 
666F 726E” 
2039 3331" 
9940 0097" 
0605 0000" 
009A 0008" 
0008 0000" 
000C 2800" 
5769 6E64" 
6560 6F6E^ 
1465 7320" 
6E61 6069" 
6E64 29ED^ 
6065 6E75" 
6163 6820" 
2061 2077" 
7700 A000" 
0008 003C” 
0000 А000" 
0022 2269" 
656E 6564" 
636C 6F73" 
6F72 2074" 
696E 646Ғ” 
206F 7264" 
6861 6E67" 
1468 6520" 
2069 7300” 
009A 0008" 
0008 0000" 
0072 0022" 
6F6D 6174" 
6C79 2075" 
6564 2074" 
666C 6563" 
D61E 6865" 
2077 696Е” 
6F72 6465" 
6974 6820" 
A000 99A1" 
001С 0000" 
A000 9828" 
2214 6F70 
646F 7720" 


$^6174 2074 6865 2074" 
%”6Ғ70 206Ғ 6620 7468" 


© The Best of MacTutor, Vol. 5 


$6520 6065 6E75 2C29" 
%”0А22 2061 6E64 2073" 


$^бЕ2@ 
$^6869 
$“6C6C 
$^6279 
%”6500 
$"0008 
$^0000 
$0022 
$2074 
$^6772 
%”656С 
%”206Е 
%”6265 
%”726Е 
%”6820 
$^696E 
$^99А1 
%%”0000 
%”9828 
%”6865 
$"0DA0 
$"08FF 
$^0040 
%”А000 
$“FFDC 
$“A000 
%”7520 
$6420 
$ *656Е 
$ *6Е75 
$2909 
$^6 160 
$^6960 
%%7079 
%”6500 
%”0008 
$0000 
$“0022 
$^1265 
$2077 
$7365 
%%416Е 
7469 
$2074 
$“6F67 
$“6E63 
$^00A0 
$"08FF 
%”00А0 
%%2222 
$°7465 
%”6С20 
%”2063 
%6173 
$”656E 
77474 
$"4061 
$°7220 
$*99A1 
$^0000 
%”9828 
$7420 
$7420 
$^626C 
%”2049 
$^6C29 
$72074 
+7263 
$"6C66 
$"0097 


6F6E 
T320 
2064 
2014 
A000 
000С 
А000 
2240 
6865 
6160 
6620 
6Ғ74 
2063 
6564 
6061 
696Е 
009A 
00D8 
00А2 
2060 
0099 
ECO 
0098 
99A1 
0000 
982A 
6361 
1468 
7520 
7220 
IF70 
T320 
106C 
696E 
A000 
FFCC 
A000 
224D 
T36F 
6974 
6469 
206 1 
636C 
6869 
1261 
6С75 
0099 
8С00 
0098 
636Ғ 
2050 
T36F 
6F64 
2062 
2013 
6564 
6320 
2869 
009A 
0008 
00Ғ2 
646Ғ 
6765 
6973 
276C 
C218 
6865 
6528 
292E 
A100 


2E20 2054" 
6973 2061" 
6F6E 6520" 
29C4 0368" 
99A1 099A" 
0000 0008" 
9828 0092" 
4445 463B" 
2070 726Ғ” 
2069 7473" 
6E65 6564" 
2029 061Е” 
6F6E 6365" 
2017 6974" 
696Е 7461" 
6700 А000" 
0008 FFFC^ 
0000 A000" 
0022 QAT4" 
656E 752E” 
A100 9А00" 
0000 0800" 
2810 0100” 
009А 0008" 
0008 0000" 
1022 596Ғ” 
6Е20 6164" 
6973 2060” 
746Ғ 2079" 
бЕТТ 6Е20" 
T26F 6772" 
6219 2073" 
1920 636Ғ” 
6720 7468" 
99А 1 009А” 
0000 0008" 
9828 0002" 
4445 4620" 
7572 6365" 
6820 5265" 
742E 2020" 
1229 0921" 
6520 6F6E” 
7320 7072" 
6D2C 2069" 
6469 6E67" 
A100 9400" 
0000 0800" 
2800 Е200" 
6070 6С65" 
6173 6361" 
7572 6365" 
652C 2068" 
2908 1Ғ65" 
1562 6069" 
2074 6Ғ20" 
5475 746Ғ” 
6600 А000" 
0008 ҒҒАС” 
0000 А000" 
0022 2269" 
6573 6Е27" 
1420 1015" 
6865 642C” 
6C20 7265" 
6561 7365" 
2073 6F75" 
6079 7365" 
А000 99А0" 
9600 0606" 


$"0000 0002 03A1 009A" 
$^0008 FFFA 0000 0025" 


); 


$^0000 A000 9804 0500” 
$^0012 2800 2800 0806" 
$^5769 6Е64 6F77 A000" 
%”99А0 0097 A000 80А@" 


%”0083 


FF” 


resource ‘PICT’ (1002, 
“Attic”, 
purgeable) ( 


1125, 

(7, 1, 
$^1101 
%%0100 
$^3201 
%%0000 
%”1844 
$^01EF 
$"^100 
$0002 
$“FFFA 
$"A000 
%”0000 
$7474 
$*7477 
%”А000 
%”0500 
$^9400 
%”Е600 
%”0000 
$°2241 
$"6F66 
$^6973 
$^6C6C 
$"146F 
$7072 
$^696E 
$ *6 16Е 
$ “6275 
%”29Е2 


306, 
A000 
0A00 
F 10A 
0000 
0009 
0700 
9600 
03A1 
0000 
9803 
122B 
6963 
6172 
97A1 
0000 
0800 
0040 
0C28 
7414 
7477 
2061 
204D 
7329 
6F67 
6720 
792E 
7369 
0100 


497), 

82А0 008С” 
0700 0701" 
0000 0000" 
0800 1800" 
0009 0130" 
0200 0248" 
0606 0000" 
009А 0008" 
0048 0000" 
0003 0405" 
BA2B 0Е41" 
2053 6Ғ66" 
65A0 0099" 
0096 0006" 
0203 А100" 
5000 0000" 
0098 0400" 
0040 0010” 
6963 2053" 
6172 6520" 
2073 6061" 
6163 696Е” 
DC22 6820" 
7261 6060” 
636Ғ 6070" 
2069 6Е20" 
6E65 7373" 
А000 99А1" 


%”009А 0008 004С 0000" 
%”00Е6 0000 А000 9828" 
$"005D 0010 2273 696Е” 
$^6365 2031 3938 362E” 
$"2020 5765 2064 6F20" 


%”6120 
$7920 
$20722 
$6465 
$032 
$7265 
$°7574 
$6572 
$“009A 
$^00Еб 
%”0060 
%”6Ғ75 
$2068 
$°726F 
$^2057 
$08 18 
$“6F6E 
$°7072 
$^696E 
$A 100 
$9000 
$"2800 
$^"0099 
$^1co0 
$0098 
$6361 
$6561 
$77920 


766 1 
6F66 
126B 
616C 
2061 
1161 
6C69 
2C0D 
0008 
0000 
00 1D 
1220 
6E6F 
6475 
6520 
6F20 
1412 
6F67 
672E 
9A00 
E600 
1000 
A100 
0000 
2A 10 
6Е20 
6368 
6061 


7269 6574" 
2077 6F29" 
3820 0249" 
696Е 6572" 
2073 6861" 
1265 206Ғ” 
2901 056Е” 
А000 99А1" 
003С 0000" 
А000 9828" 
2269 7320" 
6265 7314" 
TI6E 2070" 
6374 2-20" 
616C 7329" 
646F 2063" 
6163 7420" 
1261 6060” 
00А0 0099" 
0800 2000" 
00А0 0098" 
1001 00А0" 
9А00 0800" 
Е600 00А0" 
1Е57 6520" 
6265 2012" 
6564 2062" 
696C 2061" 


%”743А 00Ай0 0099 A100" 
$^9400 0800 0С00 0000" 


401 


%”Е600 00А0 0098 2A10" 
$^0100 А000 99A1 009A" 
$^0008 FFFC 0000 00Е6" 
$^0000 A000 982A 1022" 
$"2020 2020 2020 2020" 
%%2020 2020 2020 2020" 
%%2020 2020 2020 2020" 
%%2020 2020 2020 2041" 
$"1414 2991 0С69 6320" 
$^536F 6674 7761 7265" 
%”00А0 0099 A100 9A00" 
$*08ЕЕ ЕС00 0000 E600" 
$"00A0 0098 2800 В000" 
$?1D22 2020 2020 2020" 
$"2020 2020 2020 2020" 
$"2020 2020 2020 2020" 
%%2020 2020 2020 2020" 
$°2050 2E4F 298F 0А2Е” 
$^2042 6F78 2032 3139" 
%”00Ай 0099 A100 9A00" 
$^08FF DC00 0000 E600" 
%”00А0 0098 2800 С000" 
$^1022 2020 2020 2020" 
$2020 2020 2020 2020" 
%%2020 2020 2020 2020" 
$"2020 2020 2020 2020" 
$°2047 6F6C 2990 1865" 
$^7461 2C20 4361 6C69" 
$^666F 726E 6961 2020" 
$^2039 3331 3136 ODA" 
$0099 A100 9А00 QBFF^ 
%%СС00 0000 E600 OOAD" 
$0098 2800 0000 1001" 
%”00Ай0 0099 A100 9А00" 
$“O8FF BCOS 0000 E600" 
%”00А0 0098 2A10 2257" 
%”6520 616C 736F 206Ғ” 
$^7065 7261 7465 2061" 
%%”2062 756C 6C65 7469" 
$^6E20 626F 6172 6420" 
$^7329 0422 7973 7465" 
%%6020 6174 2028 3830" 
$?3529 2036 3833 2030" 
%%”3332 322C 2062 6574" 
$7765 656E 2074 2966" 
$^0368 6500 А000 99A1" 
$"009A 0008 FFAC 0000" 
$"00E6 0000 A000 9828" 
$^00FD 0010 2268 6F75" 
$^7273 206F 6620 363A” 
$"3030 2050 4020 616E” 
$^6420 323A 3030 2041" 
%%402С 2050 6163 6929" 
$^D822 6669 6320 7469" 
$^6D65 2C20 7365 7665" 
$^6E20 6461 7973 2061" 
%%2077 6565 6B2E 2020" 
$^506C 6561 2903 0373" 
$^650D A000 99A1 009А* 
$0008 FF9C 0000 00Е6" 
%%0000 A000 9828 0100” 
$^0010 1566 6565 6C20" 
$^6672 6565 2074 6Ғ20" 
$”6361 6C6C 2069 6E21" 
%”А000 99A0 0097 A100" 
$9600 0606 0000 0002" 
$^03A1 009A 0008 FFFD^ 
%%0000 0060 0000 A000" 
$^9800 000A 2873 1722" 
$"A920 3139 3838 2062" 
$^7920 436C 6966 666Ғ” 
$°7264 2053 746F 7279" 
$^2061 6E64 2041 7474" 
$6963 29AC 0920 536Ғ” 


402 


$”6674 7761 7265 А000" 
%”0940 0097 А000 8DAQ" 
$0083 ҒҒ” 


д 
[F*XXXXXXXXOOOOOOOOOEEXEEXXX 
Alert resource 


resource ‘ALRT’ (1001, 
“Message”, purgeable) ( 
(0, 0, 122, 300), 
1001, 
( /* array: 4 elements */ 
/* (1) */ 
OK, visible, sound!, 
/* [2] */ 
OK, visible, sound], 
/* [3] */ 
OK, visible, sound!, 
/* (4) */ 
OK, visible, sound! 


) 


‚ 
/®*®ХХЖЖЖЖХХЖХЖЖЖЖАЖЖЖАЖЖЖЖЖАЖЖЖЖЖЖЖ 


Item list resource 
жкккккккккккксксккксккккккккккккккксккскок 
resource ‘DITL’ (1001, 
“Message”, purgeable) ( 
( /* array DITLarrau: 2 
elements */ 
/* (1) */ 
(92, 120, 112, 180), 
Button ( 
enabled, 
“ок” 


), 

/х (2) */ 

(10, 10, 74, 290), 

StaticText ( 
disabled, 
"Sorry! This program” 
* can open only 18 wi” 
“ndows at one time Ci” 
“f it opened more, th” 
“e menu would be too “ 
“long for the screen)’ 
“мж 


) 
) 


; 
ТЫ 21222222222. 
Window resources 


/ 
resource ‘WIND’ (1001, 
purgeable) ( 
(0, 0, 200, 320), 
documentProc, 
invisible, 
goaway, 
0x0, 
“untitled” 
д 
resource ‘WIND’ (1002, 
purgeable) ( 
(0, 0, 200, 320), 
zoomDocProc, 
invisible, 
-1, 
0x0, 
“untitled” 


P 
J5XXEEEXEEXEXEUDOODOOOOOROOEORE 
Multifinder resource 


resource ‘SIZE’ (-1) { 


savescreen, 
acceptSuspendResumeEvents, 
enableOptionSwitch, 
cannotBackground, 
MultiFinderAwere, 

98304, 

98304 


; 
Ы 2 522222222222 222222222222) 


Some Standard Declarations 
This first bit of code is a simple unit that I include in all my 
stuff these days. Every time I use a new low-memory global, I 
stick it in here. I keep the unit in the "PInterfaces" folder, so I can 
use it easily in any program. 


(ЖЖЖЖЖЖЖЖЖХЖЖЖХЖХХҖХЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Common .p 
Declarations for 
dynamic Window menu demo. 
(c) 1988, by Clifford Story 
& Attic Software 
ЖЖЖЖЖЖЖЖХАЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖХЖЖХЖЖЖЖЕЖЖЖЖЖЖ) 


untt Common; 
(ЖЖЖЖЖЖЖЖХЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ)) 


interface 
O33 2235322955525 5555559555 553555555 53 3 ЖЖ 


Key codes: 

ххх У 

const 
enterkey = 3; 
backspace = 
tabkey = 9; 
returnkey 
clearkey = 
lef tarrow 
rightarrow 
uparrow 
downarrow 
periodkey 


5 о 
С ~ - ~ - 
е» 
` 


н и 
" "n CO P2 ими 
> 
me 
`. - 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖ 

Dialog items: 

KXXEKKKAAAARAKAKAA EAA AKA AAA AERA KKK У 
themask = 3; 

(ECOOOOOOODODDÓOOOOOOODODOOO XOOOOOOOOOEOEOE XX 

Low-memory globals: 

X XxxoxcoxoxoooocoOOIOQcOCOIECICIE EG IGIODIOOGIEOIGIGOOIOOOEG CE XX X XC +) 
applscretch = $478; 


bootdr ive = $210; 
curappname = $910; 
curdirstore = $398; 
currentad = $904; 
findername = $2E0; 
fsfcblen = $3F6; 
grayrgn = $9EE; 
iaznotify = $33C; 
mbarheight = $ BAA; 
menuf lash = $A24; 
resload = $A5E; 
rom85 = $28E; 
sfsavedisk = $214; 
sysmap $458; 


windowlist = $9D6; 


(ЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖАЖЖЖЖЖАЖЖЖЖЖЖЖЖ 


Standard tupes: 
XXXXX1X4X1XXXXXXXFXFXXXXXXXXXF2XXXXXXXXXXXXXXX) 


type 
logical = boolean; 
long = longint; 
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shor tpointer = “integer; 
longpointer = “long; 
Qoeoooopoocpeoopoocooepeoopoooooooooooocooceg) 


end. 
Qoeoeepeooocooocooopeoopboooooocooooooooeoeee) 


The Menu Definition 
An MDEF is called to do three things: draw the menu, hit- 
test the mouse location, and calculate the size of the menu 
rectangle. 


Drawing the Menu 

The menu has two parts: the first two items, which are fixed, 
and the list of open windows. I've hard-coded the first two items, 
since I know what they are. Note that if the "Zoom Front 
Window" item is disabled, then it is grayed out by drawing a gray 
rectangle over it. 

To draw the list of open windows, I start with the window 
whose pointer is stored in the low-memory global “windowlist”. 
The windows form a chain, with each window record including 
a pointer to the next one; the final window has a nil pointer in the 
"nextwindow" field. So I walk down this list, looking for 
windows to add to the menu. I'm only going to show application 
windows, since DA windows may not have titles, and of course 
ГІ omit hidden windows. 


Hit-Testing the Mouse 

This is simple, since each menu item is 16 pixels high - just 
divide the distance from the top of the menu by 16 (result: a 
number in the range from 0 to the number of menu items minus 
one) and add one (since the first item is item one, not item zero). 

There'sasmall complication: if the item is disabled, then the 
routine should return zero (no choice). 

The “whichitem” argument is a var parameter that initially 
contains the value of the last choice. If the newly-calculated item 
is the same as the last choice, then nothing has changed, so there's 
nothing else to do. If it is different, then the old item should be 
un-highlighted and the new highlighted. 


Calculating the Menu Size 

This routine must compute the width and height of the menu 
rectangle and update the menu record accordingly. The approach 
here is similar to that of the draw routine: hard-code the fixed 
items and walk the window list for the rest, looking for the widest 
menu item. 

Note the formulae by which the width of an item is calcu- 
lated. I worked these out with screen shots and fatbits, and they 
(with the corresponding formula in the draw routine) will pro- 
duce a menu identical to one created with the standard MDEF. 


(YYXXKXXXXXKXXXKXXXXXXXXXXKXXKXXXXXXXXXXXXXXX 
Window Menu.p 

MDEF for dunamic Window menu demo. 

(c) 1988, by Clifford Story 


& Attic Software 
ЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖАЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


unit WDEF; 
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Qeeeooceccceoooeceoceoooobceeeceeeec eooeoee eec) 


interface 
(Qooopboocooceceecocoobooeooeoeooeoooooooopeeec erc) 


uses memtypes, quickdraw, osintf, 
toolintf, Common; 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЕЖЖЖЖЖЖ 


procedure menudef (nessage : integer; themenu : MenuHandle; 
var menurect : Rect; hitpoint : Point; var whichitem : 


integer ); 
(Жжжж КЖК) 
implementation 
ФАР EERE KAKA EERE KEKE kk ) 
type 
QDrecord = record 
randseed : long; 
screenBits : BitMap; 
arrow : Cursor; 
dkGray : Pattern; 
ltGrag : Pattern; 
gray : Pattern; 
black : Pattern; 
white : Pattern; 
thePort : GrafPtr; 
end; 
QDpointer = ^QDrecord; 


(REERER EERE KARA EERE EAE RE ER EEK AAA AK EKER ) 


procedure menudraw(themenu : 
Rect); forward; 
procedure menuchoose(themenu : 
Rect; 

hitpoint : Point; var whichitem : 
procedure menusize(themenu : 


MenuHandle; var menurect : 
MenuHandle; var menurect : 


integer); forward; 
MenuHandle); forward; 


А 322552 2222222222224444423442%) 

($R-) 

($SC+) 

(Coeoeeooceocooocpeoepoopbooooooooeooocoooooer) 

procedure menudef (message : integer; themenu : MenuHandle; 
var menurect : Rect; hitpoint : Point; var whichitem : 

integer); 


begin 
case message of 
mDrewMsg : menudraw(themenu, menurect); 
mChooseMsg : menuchoose(themenu, menurect, 
hitpoint, whichitem); 
mSizeMsg : menusizeCthemenu); 
end; 
end; 


CQpoooeoooocoooooooccoopeoocopeooecoooceooceeexc) 


function QDglobals : QDpointer; 
var 


thepointer : longpointer; 
begin 
thepointer :- longpointer(currentad); 


thepointer := longpointer(Cthepointer^); 
QDglobals := QOpointerClongCthepointer^) 
- sizeof(QDrecord) + sizeofCGrafPtr)); 
end; 


6 352 КККК у 


procedure menudrawCthemenu: MenuHandle; var menurect: Rect): 
var 


height : integer; 

width : integer; 

therect : Rect; 

thewindow : WindowPeek; 
begin 


height := menurect.top + 12; 
width := menurect.left + 12; 


Movelo(width, height); 

DrawStringC'Zoom Front Window’); 
MoveTo(menurect.right - CharWidthC'W^) - 15, height); 
DrawChar(chr(17)); 

DrawChar( 'W^); 


if not BitTstCethemenu^^ .enableFlags, 30) then begin 
PenPat(QDglobals* .grau); 
PenMode(patBic); 
with menurect do 
SetRect(therect, left, top, right, top + 16); 
PaintRectCtherect); 
PenNormal ; 
end; 


height := height + 16; 
MoveToCmenurect.left, menurect.top + 24); 
LineCmenurect.right - menurect.left, 0); 


thewindow := WindowPeek(longpointer Cwindowlist)*); 


while thewindow © nil do 
with thewindow^ do begin 
if visible and (windowkind = userKind) then begin 
height := height + 16; 
MoveToCwidth, height); 
DrawString(titlehandle**); 
end; 
thewindow := nextwindow; 
end; 
end; 


(YXXXX1XX1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) 


procedure menuchoose(themenu : MenuHandle; var menurect : 


Rect; 

hitpoint : Point; var whichitem : integer); 
var 

theitem : integer; 

therect : Rect; 
begi 


gin 
if PtInRect(hitpoint, menurect) then 
theitem := 1 + CChitpoint.v - menurect.top) div 16) 
else 
theitem := 0; 


if not BitTstC@themenu** .enableFlags, 31 - theitem) then 


theitem := 9; 


if theitem O whichitem then begin 

therect := menurect; 

therect bottom := therect.top + 16 * theitem; 

therect.top := therect.bottom - 16; 

Inver tRect(therect); 

if whichitem > 0 then begin 
therect.bottom := menurect.top + 16 * whichitem; 
therect.top := therect.bottom - 16; 


Inver tRect(therect); 
end; 
whichitem := theitem; 
end; 


end; 


(Y1X3XXXX5XXXXX1XXXXX1XXXX1XXXXXXXXXXXXXXXEK) 
procedure menusize(themenu : MenuHandle),; 


var 
thewidth : integer; 
theheight : integer; 
thew indow : WindowPeek ; 
newwidth : integer; 
begin 


TextFontCsystemFont); 


404 


TextSize( 12); 
TextFaceC[ 1); 


theheight := 32; 
thewidth := StringWidthC'Zoom Front Window’) + 
CharWidthC'W^) + 39; 


thewindow := WindowPeekClongpointer(windowlist)^ 2; 


while thewindow © nil do 
with thewindow^ do begin 
if visible and (windowkind = userKind) then begin 
theheight := theheight + 16; 
newwidth := StringWidthCtitlehandle^^) + 16; 
1f newwidth > thewidth then 
thewidth := newwidth; 
end; 
thewindow := nextwindow; 
end; 


themenu^^.menuHeight := theheight; 
themenu^^.menuWidth := thewidth; 

end; 

(Жжжж кка) 


end. 
CxoXxidoooocoooooooooooocooboooocobooocoboooexee) 


The Main Program 
This is, I think, a pretty straight-forward program, so I won't 
say much about it except for four features: menu maintenance, 
opening and closing windows, zooming windows, and window 
selection. 


Menu Maintenance 

I thought I said there wouldn't be any maintenance? Well, 
there is a little, but not very much. 

When the length of the menu changes, I have to call 
CalcMenuSize to provoke the Menu Manager into calling the 
MDEF with an “mSizeMsg” message. If I don't do this, either 
there will be a blank space at the bottom of the menu, or the last 
item will be missing. 

The size of the menu changes whenever I open or close a 
window, so I call CalcMenuSize at these times. 


Opening and Closing Windows 

The Window menu doesn’t scroll; that limits it to 18 win- 
dows (20 items minus the zoom item and the dividing line). So, 
logically, I ought to limit the program to 18 windows as well. 

If the program can open only 18 windows, there’s no reason 
to open them dynamically and clutter up the heap with a bunch 
of fixed objects (WindowRecords). So instead I'll declare a 
global array of WindowRecords. I'll just pass the address of one 
of these (instead of a nil pointer) for the wStorage argument of 
GetNewWindow. 

Ah, but now I have to keep track of which records belong to 
open windows, and which are free. This is actually easy to do. 

First, extend the WindowRecord with a couple of new fields 
(see the datarecord declaration below): an integer ID and an 
integer “pointer” to the next record. The ID is just the index of 
the record in the array, and the "next" field initially points to the 
next record in the array (with the last one -1). Then there's 
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another global, an integer called FREE, which initially points to 
the first record in the array. 

What I'm doing is keeping a list of all the free Window- 
Records. Initially, they're all free and, sure enough, they’re all 
on the list. Each time I open a window, I pass the address of the 
Window-Record pointed to by FREE, and set FREE to that 
record’s “next” field. That pops it off the list. When I close a 
window, I add the WindowRecord back to the free list, by setting 
its “next” field to FREE, and FREE to its ID. If FREE is ever - 
1, then the list is empty, and I can’t open a window. 


Zooming: When? 

The first question is, when should I allow zooming? 

Since I’m zooming with ZoomWindow (see my Corners 
article, April 1989, for another method that works on all ROMs), 
I don’t want to allow zooming on the 64K ROM. So I keep a 
global flag, OLDROM, to tell me if the program is running on the 
64K ROM, and I keep the “Zoom Front Window” item disabled 
if it is. 

Also, I only want to zoom application windows. (I tried 
zooming the Alarm Clock, once, just to see what would hap- 
pen...) So if the front window isn’t an application window, I 
disable the “Zoom Front Window” item. I do this in the 
“anactivate” routine, disabling on deactivates and enabling on 
activates. 


Zooming: How? 

The short answer to this is: with ZoomWindow. Unfortu- 
nately, ZoomWindow ain’t the smartest trap in the world, or 
maybe it’s just to subtle for me. The problem is this *inZoomIn", 
"inZoomOut" nonsense. If you send it an “inZoomIn” part code, 
and it thinks the window is already zoomed in, it will do nothing. 
So I have to figure out when it thinks it’s zoomed in, and when 
it thinks it’s zoomed out. Maybe there’s an easy way; for my part, 
this is the last time I plan to use Zoom Window. 

This wouldn’t trouble me if I was only zooming from the 
zoom box, since FindWindow will tell me which part code to use. 
The problem arises because I’m also zooming from the menu. 

What I decided to do is keep a flag in the reference constant 
of each window, setting it when the window is zoomed out, and 
Clearing itotherwise. So when the time comes to zoom, I just look 
at the flag and zoom in if it’s set, and out if it’s cleared. This is 
done in the routine “zoomthewindow”. 

Now Гуе got a flag to maintain. Besides the obvious in the 
"zoomthewindow" routine, I also must initialize the flag (in 
“допем”), and clear it if the window is dragged (in “clickindrag”) 
or re-sized from the grow box (in “clickingrow”). 


Selecting a Window from the Menu 
There is a little bit of work to do when a selection is made 
from the window list in the Window menu. After all, what the 
Menu Manager returns is an integer, nota WindowPtr. I have to 
walk the window list, just like in the MDEF, until I find the 
correct window, and then select it. 
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( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Window.p 


Demo of a dunamic Window menu. 
(c) 1988, bu Clifford Storu 


& Attic Software 


ХЕЕЕ) 


program Window; 


Ceooeeooccooooooocepeooeopboocoooooooooeee ) 


uses memtypes, quickdraw, osintf, 
toolintf, packintf, Common; 


(Y1X1XFXXXXXX1XXXKXXXXXXXXXXXXXK1IXXXXXKEXKXKXXXK 


Program constants: 


XXXXXXXXXKXXX1XXXXXXXX1X1XXX1X1XX1XXXXXKXXKXXET) 


const 
applenum = 1001; 
aboutitem = 1; 
atticitem = 2; 
f ilenum = 1002; 
newitem = 1; 
closeitem = 2; 
quititem = 4; 
editnum = 1003; 
undoitem = 1; 
cutitem = 3; 
copyitem = 4; 
pasteitem = 5; 
clear = 6; 
windnum = 1004; 
zoomitem = 1; 
messagedialog = 1001; 
windownum = 1001; 
zoomwindnum = 1002; 
hoffset - 32; 
voffset = 20; 


( ЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖ 


Program tupes: 


XOOOOOOOOOROOOOODOOOOICOOROOOEOIOOOOOOEOOEOR EE ) 


type 
datarecord = record 
dummy : WindowRecord; 
recordid : integer; 
next : integer; 
end; 


datapointer = “datarecord; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


Program variables: 


ЖЖАЖАЖАЖЖАЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖААЖЖЖЖЖЖЖЖЖЖЖЖЖ ) 


var 
APPLEMENU 


FILEMENU 
EDITMENU 


WINDOWMENU 


MENUHEIGHT 
DRAGRECT 
GROWRECT 
SCREENRECT 


WINDOWS 


: MenuHandle; 
: MenuHandle; 


MenuHandle; 
MenuHandle; 


: integer; 


: Rect; 


: Rect; 
: Rect; 


: array [0.. 17] of datarecord; 
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FREE : integer; 


OLDROM : logical; 
COLUMNS : integer; 

ROWS : integer; 
WINDOWCOUNT : integer; 

DONE : logical; 

JEVENT : logical; 
MAINEVENT : EventRecord; 


(XXEEEREDOGOOOOOOOOOEO OOOOOOOOOOOOOOOOEOE) 


procedure —datainit; external; 
(жаккка ккк КККК КЕЕ) 


($R-) 
($SC*) 
(ЖЖЖЖЖЖЖЖЖЖЖЖХЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖХЖЖЖЖЖ ) 
procedure panic; 
begin 

ExitToShe11; 
end; 


6555555355535223322222224422222525222220 


procedure centerdialog( thetupe : OSType; theid : integer); 


var 
thehandle : AlertTHndl; 
begin 
thehandle := AlertTHndlCGetResourceCthetype, theid)); 
HLockCHandle(Cthehandle)); 
with thehandle^^ do begin 
with boundsRect do 


SetRect(boundsRect, 0, 0, right - left, bottom - top); 


with screenBits.bounds, 
boundsRect .botr ight do 
OffsetRectCboundsRect, (right - left - h) div 2, 
" (bottom - top - v + 2 * MENUHEIGHT) div 3); 
en 
HUn lock CHandle(thehand!e2); 
end; 


(ХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
procedure initmac; 
begin 
MaxApplZone; 
InitGraf (ëthePort); 
InitFonts; 
InitWindows; 
InitCursor ; 
Ini tMenus ; 
TEInit; 
InitDialogsC@panic); 
UnloadSeg(@_datainit); 
end; 


65552111333342442422424222222222222244220 
poscere se tupmenus; 
n 

APPLEMENU := GetMenuCapplenum); 
AddResMenuCAPPLEMENU, ‘DRVR’); 
InsertMenuCAPPLEMENU, 0); 
FILEMENU := GetMenu(filenum); 
InsertMenuCFILEMENU, 0); 
EDITMENU := GetMenuCeditnum); 
InsertMenuCEDITMENU, 0); 
WINDOWMENU := GetMenu(windnum); 
InsertMenuCWINDOWMENU, 0); 
DrawMenuBar ; 

end; 


(XXXXX3XX3XXXXXXXXXXXXXXXXXXXXXXXXXXXXKKX) 
procedure initglobals; 


var 
index ; integer; 
begin 
for index := 1 to 10 do 
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MoreMasters; 
OLDROM := BitTst(Ptr(rom85), 0); 


1f OLDROM then 
MENUHEIGHT := 29 


se 
MENUHEIGHT := shortpointer(Cmbarheight)°; 


1f GetResource( ‘PACK’, 0) = nil then 
JEVENT := false 
else 
JEVENT := (NGetTrapAddress($A868, ToolTrap) 
€ NGetTrapAddress($A89F, ToolTrap)); 


with screenBits.bounds do begin 
SetRectCDRAGRECT, left + 5, top + MENUHEIGHT + 5, 
right - 5, bottom - 25); 
SetRect(GROWRECT, 168, 100, right - left - 18, bottom 
- top - MENUHEIGHT - 10); 
SetRectCSCREENRECT, left + 5, top + MENUHEIGHT + 25, 
right - 5, bottom - 5); 
COLUMNS := 1 + CCright - left - 338) div hoffset); 
ROWS := 1 + CCbottom -top -MENUHEIGHT - 230) div voffset); 
end; 
for index := 8 to 17 do 
with WINDOWS[ index] do begin 
recordid := index; 
next := index + 1; 


end; 
WINDOWS(17] .next := -1; 
FREE := @; 


WINDOWCOUNT := 0; 
DONE := false; 


end; 


(жх) 
procedure clickapplemenu(theitem : integer); 


ver 
itemname : Str255; 
savedpor t : GrafPtr; 
dummy : integer; 
newport : GrafPort; 
thepicture : PicHandle; 
therect : Rect; 

begin 


if theitem > 3 then begin 
GetItemCAPPLEMENU, theitem, itemname); 
GetPort(savedport); 
dummy := OpenDeskAccCitemname); 
SetPort(savedport?; 
end eise if theiten « 3 then begin 
InitCursor; 
GetPort(savedport?); 
OpenPortCÓnewport?); 
SetPor tC@newpor (0; 
thepicture :=PicHandle(GetResource( ‘PICT’, 1008+ theitem)); 
with thepicture**.picFrame do 
SetRect(therect, 0, 0, right - left, bottom - top); 
with screenBits.bounds, therect.botright do 
OffsetRect(therect, (right - left - h) div 2, 
(bottom - top - v) div 3); 
DrawPicture(thepicture, therect); 
repeat until Button; 
ClosePor tC @newpor t ); 
EnableItemCEDITMENU, 0); 
DrawMenuBar ; 
PaintBehind(WindowPeek(FrontWindow), RgnHandle( 
longpointer(grayrgn)* 2); 
SetPor tCsavedpor t ); 
FlushEventsCeveryEvent, 0); 
end; 


end; 
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(YxY1XX1XXXXXXXXXXXXXXXXXXXXXX1XXXXXXXXXKXX) 
procedure placewindow(thewindow : WindowPtr); 


var 
left integer ; 
top integer; 
begin 


left := 5 + hoffset * (WINDOWCOUNT mod COLUMNS); 
top := 5 +MENUHEIGHT +voffset *C1 + CWINDOWCOUNT mod ROWS)); 
MoveWindowCthewindow, left, top, true); 

end; 


(ЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖ ) 
procedure donew; 


label 
100; 
var 
dummy integer ; 
windowtype : integer; 
thew indow : WindowPtr ; 
thestring : Str255; 
begin 
if FREE < 0 then begin 
InitCursor; 


centerdialogC'ALRT^, messagedialog); 
dummy := Alert(messagedialog, nil); 
goto 100; 

end; 


1f OLDROM then 

windowtype := windownum 
else 

windowtype := zoomwindnum; 


thewindow := GetNewWindow(windowtype, 
@WINDOWS[FREE], WindowPtr(-1)); 
p lacewindow( thewindow); 


WINDOWCOUNT := WINDOWCOUNT + 1; 
NumToStringCWINDOWCOUNT, thestring); 
SetWTitleCthewindow, concat( 

‘Window Without a Title #” thestring)); 


ShowW indowCthewindow); 
CalcMenuS ize CWINDOWMENU); 


FREE :- WINDOWSIFREE  .next ; 
100: end; 


655552 2522222222222222222252222222224225 


procedure doclose(thepeek : WindowPeek); 
begin 
1f thepeek* .windowkind < 0 then 
CloseDeskAcc(thepeek .windowk ind) 
else begin 
CloseWindowCWindowPtr(Cthepeek)); 
with datapointerCthepeek2^ 
do begin 
next := FREE; 
FREE := recordid; 
end; 
CalcMenuS ize CWINDOWMENU); 
end; 


М 


(ЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖ ) 
ргоседиге doquit; 


ver 
thelong : longpointer; 
thepeek : WindowPeek; 
begin 
thelong := longpointer(windowlist2; 
thepeek := WindowPeekCthelong^); 
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while thepeek © п11 до begin 


doc lose( thepeek ); 
thepeek := thepeek^.nextwindow; 
end; 
DONE := true; 
end; 
CXoococcoocoeoopbocoeocooocoooooocoooopboeooeec) 
procedure clickfilemenu(theitem : integer); 
begin 
case theitem of 
newitem : donew; 
closeitem : doclose(WindowPeekCFrontWindow2); 
quititem : doquit; 
end; 
end; 
CQeoeeoococooooocpooooooococooooocoooooooceoeeec ) 
procedure zoomthewindowCthewindow : WindowPtr); 
begin 
1f GetWRefConCthewindow) = 0 
then begin 


ZoomWindowCthewindow, inZoomOut, true); 
SetWRefConCthewindow, 1); 
end else begin 
ZoomWindowCthewindow, inZoomIn, true); 
SetWRefConCthewindow, 0); 
end; 
end; 


(Qoeeoococoooeoooooocoocoooooooooooooobcoeee) 


procedure clickwindowmenuCtheitem : integer); 
var 

thew indow : WindowPeek ; 
begin 


if theitem = 1 then 
zoomthewindowC(FrontWindow) 
else if theitem > 2 then begin 
theitem := theitem - 2; 
thewindow := WindowPeekClongpointer(windowlist?^); 
while (not thewindow^.visible) 
or Cthewindow^.windowkind € userKind) do 
thewindow := thewindow^.nextwindow; 
while theitem > ! do begin 
theitem := theitem - 1; 
repeat 
thewindow:= thewindow* .nextwindow; 
until thewindow* visible and (thewindow* .windowkind = 
userKind); 


end; 
Se lectW indowCWindowP tr( thew indow)); 
end; 
end; 


АМ EKER ERE ЖКК ЖККУ 


procedure checkmenuCthewindow : WindowPeek); 
begin 
DisableItemCEDITMENU, 0); 
DisableItemCWINDOWMENU, zoomitem); 
16 thewindow = nil then 
DisableItemCFILEMENU, closeitem) 
else begin 
if thewindow^ .windowkind © userKind then 
EnableItemCEDITMENU, 0) 
else if not OLDROM then 
EnableItemCWINDOWMENU, zoomitem); 
EnableItemCFILEMENU, closeitem); 
end; 
; 


655555555222 2222252552552225299444449 


procedure clickinmenu; 
var 


choice : long; 
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begin 
checkmenu(WindowPeek(FrontWindow)); 
choice := MenuSelect(MAINEVENT.where); 
case HiWord(choice) of 


applenum : clickapplemenu(LoWord(choice)); 
filenum : clickf ilemenuCLoWordCchoice2); 
editnum : 4f SystemEditCLoWord(choice) - 1) then; 
windnum : clickwindowmenuCLoWord(choice)); 
end; 
HiliteMenuC0); 


end; 


(ЖЖЖХЖЖАЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖАЖЖЖЖЖЖЖЖХ ) 
procedure clickindrag(thewindow : WindowPtr ); 
begin 
DragWindow( thew indow, 
MAINEVENT.where, DRAGRECT); 
SetWRefCon(thewindow, 0); 
end; 


(жж) 
procedure clickingrow(thewindow : WindowPtr); 
var 

newsize : long; 


begin 


newsize :- GrowWindowCthewindow, MAINEVENT.where, GROWRECT); 


if newsize © Ø then begin 
InvalRectCthewindow^ .portRect); 


SizeWindowCthewindow, LoWord(newsize), HiWord(newsize), true); 


SetWRef ConCthewindow, 0); 
end; 


( ЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ Ж) 


procedure clickingoaway(thewindow : WindowPtr); 
begin 
if TrackGoAwau(thewindow, MAINEVENT.where) then 
doclose(WindowPeek(thewindow)); 
end; 


(ЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 
procedure clickinzoom(thewindow : WindowPtr; thezoom : 
integer); 
begin 
if TrackBox(thewindow, MAINEVENT.where, thezoom) then 
zoomthew indow( thew indow ); 
end; 


(Y22355 3355555 73X53XX5XXXXXXXXXXXXXXX5XX53X3XXX ) 


procedure ac! ick; 
var 
location : integer; 
thew indow : WindowPtr ; 
begin 
location := FindWindowCMAINEVENT.where, thewindow); 
case location of 
inDesk : SysBeep(1); 
inMenuBar : clickinmenu; 
inSysWindow: SystemC] ick(MAINEVENT, thew indow); 
inContent : SelectWindowCthewindow); 


inDrag  : clickindrag(thewindow); 

inGrow : clickingrowCthewindow); 

incoAway : clickingoaway( thewindow); 
inZoomIn : clickinzoomCthewindow, inZoomIn); 


inZoomOut : clickinzoomCthewindow, inZoomOut); 
end; 
end; 


(OOODOOOOODOOOOOOODOOOODOOOOOOOOODOEOEXEEC) 
procedure akey; 


var 
charcode : integer; 
choice : long; 
begin 
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і? BitAnd(MAINEVENT modifiers, cmdKey) «© 0 then begin 
charcode := BitAndCMAINEVENT.message, charCodeMask ); 
checkmenu(W indowPeekCFrontWindow)); 
choice := MenuKeyCchrCcharcode2); 
if choice © 0 then begin 

case HiWordCchoice) of 
applenum : clickapplemenuCLoWord(choice)); 
filenum : clickfilemenuCLoWord(choice)); 
editnum : if SystemEditCLoWordCchoice) - 1) then; 
windnum : clickwindownenuCLoWordCchoice)2; 

end; 

HiliteMenu(@); 

end; 
end; 
end; 


(ЖЖЖЖЖЖЖАЖЖЖХЖХЖХЖЖЖЖЖХЖЖЖЖЖЖЖХЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖ У 


procedure anactivate(thewindow : WindowPtr); 
var 


savedport : GrafPtr; 
begin 
SetPor t¢ thew indow); 


DrawGrowIcon( thew indow); 


2 


Coxooocooooooooeocooooopeooocoopooooeeeeexex У 


procedure anupdate(thewindow : WindowPtr); 
var 
savedpor t : GrafPtr; 
begin 
GetPort(savedport); 
SetPort(thewindow); 
BeginUpdate(thewindow); 
ClipRectCthewindow^ .portRect); 
EraseRect(thewindow .portRect); 
DrawGrowIcon(thewindow); 
EndUpdate(thewindow); 
SetPort(savedport); 
end; 


(Y22XXXX1XXXXXXXXXKXXKXXXXXXXXXXXXXXXKXXKXKKK) 
procedure mainloop; 
ver 

dummy : logical; 
begin 

repeat 

1f JEVENT then 
dummy := waitnexteventCeveryEvent, MAINEVENT, 
GetCaretTime, nil) 


else begin 
SystemTask ; 
dummy := GetNextEventCeveryEvent, MAINEVENT); 
end; 
1f dummy then begin 
case MAINEVENT .what of 
mouseDown ; aclick; 
keyDown : akey; 
activateEvt: 
anactivate(WindowPtr(MAINEVENT.message)); 
updateEvt I 
anupdate(WindowPtr(MAINEVENT .message)); 
end, 
end; 
until DONE; 
end; 
(QOOCOEOEOEOEEOOIOOIOIOIOROIOROIOIOODIOOIOIOROIOODIOIOIOIOOOOE XC) 
begin 
initmac; 
setupmenus; 
initglobals; 
mainloop; 


end. см! 
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Getting Started in MacApp 

Apple Computer has now released MPW 3.0 final and 
MacApp 2.0b9, making Apple the first company to release a 
complete object-oriented design platform for it’s family of 
Macintosh workstations. After several years of work, the early 
developmentefforts that started with Smalltalk, Lisa Clascal, and 
early versions of MacApp have now paid off in a very stable and 
robust interpretation of the Macintosh toolbox. MacApp re- 
defines much of the standard toolbox and the familiar toolbox 
objects such as windows, events, and menus, as objects, able to 
respond to commands. Further refinements of the concept of 
windows and menus in particular extend these toolbox structures 
into the world of objects ina more flexible and powerful way than 
before. In this article, we will introduce MacTutor readers to 
object-oriented programming and MacApp in our new Mac 
OOPs column, a regular feature each month in the new MacTu- 
tor. 


MPW 3.0 Final 

To run MacApp 2.0b9, you must have the final release of 
MPW 3.0. Without it, the compiler cannot compile some of the 
MacApp source code, and some of the needed new Pascal 
interfaces are missing in prior beta versions. The final release of 
MacApp 2.0 is currently waiting delivery of new manuals but 
otherwise is supposed to be identical to 2.0b9, although reports 
this spring indicated that there were several “b9” versions run- 
ning around at the last minute. 

MacApp is delivered in source code format and is compiled 
in either “debug” or “nodebug” versions when you compile your 
own source code by specifying the MPW *'-autobuild" option. A 
paper copy of the source code is also available. Contact APDA, 
now a part of Apple Computer, for details on how to order MPW 
3.0 final and MacApp 2.0. This version really represents what 
MacTutor considers the first stable and universally usable ver- 
sion of MacApp, and we highly recommend that you get on the 
MacApp bandwagon with this version, if you haven't already. 
Currently MacApp only runs with MPW Object Pascal, but 
header files are being developed to interface the MacApp object 
libraries with Apple's new C++ Compiler, and Think Technolo- 
gies is preparing a new version of Lightspeed Pascal to run with 
MacApp. 


Objects & C 
C++ has been delayed by AT&T, which is controlling it's 
release. Apple has been allowed only 200 copies until the final 
release from AT&T, which just took place at the end of June. It 
will be several months from that date before Apple can prepare 
it for release to developers. C++ was chosen over the other 
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object-oriented C pre-processors because Apple believes it will 
be a defacto standard in the industry. Think Technologies is also 
preparing another release of their Lightspeed C compiler, which 
will include a form of Objective C, a slightly different object- 
oriented version of C. Most C people feel Objective C has a much 
more natural syntax than C++, which places power and flexibility 
before everything else, at the expense of a straight forward 
syntax. The C world in general really does not have a good syntax 
for objects in comparison to Object Pascal, which has only one 
standard implementation in contrast to the three or four imple- 
mentations floating around in the C world. 


What is MacApp? 

MacApp is a set of object classes that re-defines the Macin- 
tosh user interface in the form of objects. The keyword OBJECT 
in Object Pascal implements a new kind of RECORD data 
structure that bundles together variables (i.e. fields), with proce- 
dures (i.e. methods), which act on those variables. Together, the 
fields and methods form an object and by virtue of those bundled 
methods, the object can "respond" to commands. Objects can 
inherit fields and methods from other objects, and they can have 
methods which override the methods of the objects they are 
descended from. MacApp defines TObject(Object) as the basis 
for all the objects defined in MacApp. TObject differs from it's 
inherited Object class by having a method to clone itself. From 
TObject all the other MacApp objects are developed. In 
MacApp, it is customary to start all object names with a “T” and 
all data fields within objects with "f", to distinguish object 
variables from methods. Figure 1 shows the object hierarchy of 
MacApp. The indentation shows the nested hierarchy of the 
classes. 


A Simple MacApp Program 

In our demo program this month, we present a simple 
MacApp program that calls SysEnvirons and displays all the 
information about what type of Mac we are running on, and calls 
PrGeneral to display the resolution of the currently selected 
printer driver. These two functions are shown in the Sample 
Menu as "Query Mac" and "Query Printer". Our program is 
based on a similar program written in Lightspeed Pascal and 
published by myself and Dave Kelly a few months ago in 
MacTutor. That program took several weeks of hard work to 
write. This MacApp version took a few hours and is much more 
functional than the original. The speed with which programs can 
be implemented that follow the expected Macintosh User Inter- 
face Guidelines is the major advantage for using MacApp. This 
is because the objects you use in your program inherit from 
MacApp object classes, methods that know how to respond to 
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events, menus and errors. In the case of this month's program, I 
wrote a draw method that calls SysEnvirons and PrGeneral and 
displays the results. Everything else was standard MacApp code 
that gave the program a long list of features: multi-window, 
Multifinder compatible, desk accessory support, clipboard sup- 
port, Open, Save, Print, scrolling, grow window, zoom window 
and an about box. Writing all that functionality easily takes a few 
weeks or more, but with MacApp it all comes for free by virtue 
of the methods objects inherit from the pre-defined MacApp 
object classes. 


MacApp Classes 

As figure 1 shows, from TObject, MacApp defines an 
abstract object called TEvtHandler and from this object, the 
familiar Macintosh objects are descended, including the applica- 
tion object, the document object, the window object and a new 
thing called the view object.In MacApp, the application program 
itself is considered an object that “knows” how to open docu- 
ments. Documents in turn are objects which “know” how to read 
and write themselves to disk. Views are objects that “know” how 
to display some portion of the document on the screen, in a 
window. Note that a window itself, is defined as a view object 
even though we think of windows as semi-hardware things that 
display views of our data. Think of a view as a further refinement 
of the window, allowing a more flexible and general way to 
present data in the window and try not to think of the window as 
a view, even though it is, because that’s confusing. 


Class Heirarchy in MacApp 
ТОбјесї = OBJECT (от UObject.p) 
TEvtHandler = OBJECT(TObject) {from UMacApp.p) 
TApplication = OBJECT(TEvtHandler) 
TDocument = OBJECT(TevtHandier) 
TView = OBJECT(TEvtHandier) 
TScroller = OBJECT(TView) 


TWindow = OBJECT(TView) 


TControl = OBJECT(TView) 


TCUMgr = OBJECT(TControl) 
TScrolBar = OBJECT(TCUMgr) 
TPrintHandler = OBJECT(TEvtHandier) 
TStdPrintHandler)TPrintHandler) 
TCommand = OBJECT(TObject) 


TUst « OBJECT(TObject) (from UList.p) 


Figure 1 


Logical Hierarchy 
Figure 2 attempts to show the logical or observable hierar- 
chy of the various MacApp classes. At the top are the application 
object and the document object. Then come the various objects 
which allow information to be displayed on the screen. Logi- 
cally, the window object comes first. Within the window, we 


define a scroller object and then a view object. The scrollerobject | 
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Logical Organization of Objects 


Ф a 


Sample 
The Application Object 


The Document Object 


The Window Object 
2. 


Тһе quick brow 
fox jumped 
over the lazy 
dogs back. 


The quickbro 
fox jumped 


Figure 2 


allows us to define regions in the window that will be scrollable. 
The view object sits on top of the scroller object and displays the 
information in the document. Thus the view and hence the 
document is scrollable by virtue of the scroller object. Scroll bars 
attached to the window interact with the scroller object to control 
the scrolling of the view. As soon as you define a view and draw 
intoit, your application becomes multi-window and scrollable by 
virtue of the view's and window's inherited behavior. By imple- 
menting views and scroller objects, you can define multiple 
independent regions in your window that can scroll and display 
information from the document object. Printing comes for free 
also, by simply having a view draw itself independent of a 
window object. 


Event Handling 

In a normal Macintosh program, you init the managers and 
enter an event loop, waiting for a mouse click or a menu 
command. Your program is built-up in top-down structured 
fashion around the event loop with procedures that implement 
each event function and each menu item. The code follows the 
eventtree structure rather than the data generated by the program. 

In MacApp, the event loop is hidden, as a part of the 
TEvtHandler object's methods that our objects inherit from 
MacApp. So where does our code go? We break it up and stick 
part of the functionality of our program with each object that is 
logical for that object to understand. Figure 3 shows how this 
works. Our TApplication object, the application itself, has meth- 
ods that implement functions the program should do if no 
document has been opened, such as putting up an about box or 
opening a document. The document object has methods that save 
and print itself. The window object has methods that zoom and 
drag the window. Anda view object that implements a palette of 
tools has a method that selects a tool from the palette. 
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Objects Handle Events 


TApplication TDocument 


Sample Sample Doe 


DoMenuCommand.About 
DoMenuCommand.Open 


DoMenuCommand.Save 
DoMenuCommand.Print 


TWindow 
z JZ Window 


DoMouseCommand.Zoom DoMouseCommand.Select 


DoMouseCommand.Drag 


Figure 3 


Menu Commands 

A major change in MacApp is that menus are linearized. 
Instead of a menu and menu items, MacApp returns a single 
"menu command” number. Objects respond to menu commands 
by having a “DoMenuCommand” method that can process the 
various menu commands that object should understand. Com- 
mands are generalized by this command number concept so that 
commands themselves are objects created by your program. This 
allows a command to respond to another command to “Undo” 
itself or "Redo" itself. Menu command objects are created by 
"DoMenuCommand" methods. Mouse command objects are 
created by "DoMouseCommand" methods. Typing command 
objects are created by “DoKeyCommand” methods. Each of 
your objects has DoMenu, DoMouse or DoKey command meth- 
ods appropriate for that object, as figure 3 illustrates. 


Our Sample Program 

Our program defines three objects; an application object, a 
document object and a view object. Our view object has a draw 
method that draws the results of the calls to SysEnvirons and 
PrGeneral. The inherited behavior of these three objects imple- 
ment all the other Macintosh User Interface features. 

The custom in MacApp is to have a main program, shown at 
the start of the program listing, begin with “M”. Then the unit for 
the program, which begins with “U” follows. The USample unit 
lists in the interface part, all of the object definitions and as is 
shown in the listing, there are three objects defined here. Follow- 
ing the object declarations, the object methods are listed in the 
implementation part, which is broken out as a separate include 
file called USample.inc1. It would be more logical I would think 
to define asingle object in each unit and to have both the object's 
declaration and it's methods in that unit. But the USES statement 
in Pascal might prevent this, since UNITS cannot use each other, 
which might be required if each unit contained the declaration 
and methods of a single object. Breaking up the methods and 
declaration of the object into two separate files seems to destroy 
the whole point of having objects. I would welcome some 


@ The Best of MacTutor, Vol. 5 


B (ШІМ  . 


This is the Mec 
environsVersion = 1 

Machine Type = MacII 
sysemVersion = 1539 

CPU Version = 68020 

has FPU = TRUE 

has Color QD = TRUE 
Keyboard Type = АЕхемк bd 
Driver Version = 49 

Sysem Ref Number = -32653 
has 128K ROM = TRUE 

has HFS = TRUE 

has Hierarchical Menus = TRUE 
has Script Manager = TRUE 
has StyleText Edit = TRUE 

has Sound Manager = TRUE 
has WaitNextEvent = TRUE 
has SCSI = TRUE 

has Desktop Bus = TRUE 


This is the printer (Driver) 
X Resolution = 300 
Y Resolution = 300 


Figure 4. Mac and Printer Queries 
comments from our readers on this point. 


The Main Program 

All main programs in MacApp look the same and look very 
much like this one. You simply init the Macintosh toolbox stuff, 
and the MacApp object stuff and then create an application 
object. Then you call the application object's init method and 
invoke the application object's run method. The run method is 
inherited from the fact that an application object isa TEvtHandler 
class object. If the MacApp error routine, FailNil, detects a 
problem in creating the application object (like not enough 
memory), then another MacApp routine, StdAlert, puts up an 
appropriate error dialog and gracefully exits. Thus our program 
gets nice error checking for free and doesn't blow up on the user 
if he is running on a machine that cannot be supported. This is one 
of the main features of using MacApp— the built-in error 
checking and pre-defined dialog boxes for dealing with those 
errors. The call to ValidateConfiguration is a MacApp version of 
the SysEnvirons trap and determines if we can run or not. By 
following this sample main program, you can create robust 
programs that will run on any Macintosh, at least long enough to 
put up a dialog and tell the user why they can't! 


USampe.p 

Our one and only unitin this program is made up of two files: 
the interface part in USample.p and the implementation part in 
USample.inc1.p. When we declare our three objects of TAppli- 
cation, TDocument and TView, we declare the data fields if any 
the object has, and the methods of that object. The application 
object has only two methods: ISampleApplication and DoMake- 
Document. This allows the application object to initialize itself 
and make a new document when the user selects New or Open 
from the File menu. 
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The document object has several methods which override 
MacApp default methods for it's inherited TDocument object 
class. Again, it has a method to initialize itself (ISampleDocu- 
ment), create a view (DoMakeViews), create a window (DoMa- 
keWindows), setup the menus (DoSetupMenus) and execute 
menu commands (DoMenuCommands). All of the code for these 
methods are simply taken from the MacApp supplied demo 
program. You don’t have to write them. You simply modify them 
for your own program. The only two methods I wrote for our 
sample are SetCmd and GetCmd, which set and return the current 
menu command, either “Query Mac" or "Query Printer". The 
custom in object oriented programming is that objects should not 
directly read or modify another object's data fields, so you write 
little methods to set and return the value of those fields. "fDat- 
аста” is the field in TSampleDocument that contains the current 
menu command. The other field in our document object is the 
document's view: fSampleView. 

The view object has two methods: ISampleView to initialize 
the view, and Draw, where the actual drawing for the application 
takes place. 


USample.inc1.p 

Once the objects are defined, we then write the code for the 
methods of each object. That listing is shown in USample.inc1.p, 
an include file for USample.p. Here all the methods and other 
Pascal procedures are listed. MacApp provides a number of 
alternatives to toolbox trap calls. One of these is NewSimple- 
Window. In our document’ s DoMakeWindows method, we call 
NewSimpleWindow, which creates a Macintosh window and 
returns a handle to a window object. By using the SELF keyword, 
we tell NewSimpleWindow to make the connection between us 
(our document) and our view (fSample View). The document has 
a view and the view is connected to a window manager window 
by this call. The other MacApp goodie is a routine that staggers 
the windows as they are created called SimpleStagger. This is a 
method that window objects inherit. 


| DoSetUpMenus 

In MacApp, menu handling is particularly easy. Remember 
how much trouble it is to check and uncheck the currently 
selected menu item? In our document's DoSetUpMenus method, 
this is very easy. We call a MacApp routine called Enable to 
enable the menu items. MacApp constantly disables everything, 
so each object has to enable the items appropriate for that object. 
Then we call something I wrote— our document’s GetCmd 
method to return the currently selected menu item. Then a call to 
another MacApp routine called EnableCheck simply checks the 
menu item if it equals the result returned from GetCmd and 
unchecks it otherwise. Four lines of code and you have a 
consistent checking and unchecking of a menu! 


Inheritance 
Remember that I said a lot of the functionality of the program 
for opening files and printing and saving was already done for 
me? Here is how it works. When my document’s DoMenuCom- 
mand method is called, I check my Sample Menu items, Query 
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Mac and Query Printer, against the command number passed to 
me by the MacApp method for handling events. If the user has 
selected the Query Mac item, I set the current command field in 
my document to indicate Mac and tell by document’s view to go 
re-draw itself. Sounds nasty doesn’t it? If the Query Printer item 
is chosen, I set the command to indicate Printer and again tell my 
document’s view to re-draw itself. When the Draw method of the 
view is called, the documents command field will indicate 
whether to draw the Mac info or draw the Printer info. That is all 
I do. All the other functionality is inherited from objects from 
which my document is descended from. So I simply call INHER- 
ITED DoMenuCommand to pass the buck back up the chain of 
objects and all the other menu items I never wrote will be 
executed by code I never wrote! That's the freebie stuff from 
MacApp! 


TSampleView.Draw 

The one thing I did write for this program was a draw method 
for my one and only view. When an update event takes place, 
each view's draw method is called. So you get free updating of 
your window's, correctly done, I might add, my simply providing 
each view with a Draw method. We check the document's 
command field by calling the documents GetCmd method, which 
returns the data field in our document that is storing the current 
menu selection. If it's Mac, we draw the Mac and if it's Printer, 
we draw the printer. 

To draw the Mac, we call call SysEnvirons and DrawString 
to display the results of all the Mac features we have. This code 
is very similar to that which we published a few months ago on 
how to call SysEnvirons. In System 7, this routine is being 
replaced by yet another attempt to describe the environment. 
Instead of SysEnvirons, we will have Gestalt! 


PrGeneral 

To draw the printer, we call PrGeneral and display the 
horizontal and vertical resolution of the printer. At first, I thought 
PrGeneral would be really neat. But now I think it is useless. All 
it does is query the currently selected Chooser print driver. If you 
are using the normal Apple LaserWriter driver to drive your high 
resolution imagesetter, PrGeneral still returns 300 by 300 so it is 
not really telling you the actual resolution of the printer at all. To 
do that, you have to write an Appletalk routine to talk to the 
Appletalk device directly. I didn't have time to do this for this 
article, but in a future column perhaps we can look at how you 
actually talk to the real thing instead of just the driver. 


Resources 

The final file in our program listing is the resource file. 
You'll note that MacApp resource files have a few more strange 
resources in them. These are the MacApp menu resources that are 
created to linearize the menu and menu item number into a single 
menu command number. MacAppcreates these automatically by 
“Post-Rezing” the resource file during the build procedure. If you 
look at your application with ResEdit, you'll find a whole bunch 
of dialogs you didn't write either. These are the error checking 
stuff that MacApp provides for you free of charge. 
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Watch for more on how to program in MacApp in our next 
column on Mac OOPs and send in your comments on this new 
column so we can provide you with the kinds of things you are 
Interested in. 


Flle MSample.p: 
PROGRAM Sample; 


($MC68020-) (The main program must be universal code) 
($MC68881-) 


USES 
UMacApp, UPrinting, (MacApp stuff) 


USample; (Our stuff) 
VAR 

gSampleApplication: TSampleApplication; 
($S Main) 
BEGIN 


InitToolBox; (essential toolbox and utilities) 
IF ValidateConfigurationC(gConfiguration) THEN 
BEGIN (make sure we can run) 
InitUMacApp(8); ( 8 calls to MoreMasters) 
InitUPrinting; ^ (init MacApp units) 


NewCgSampleApplication); (create an app object) 
FailNilCgSampleApplication); (enough memory) 
gSampleApplication.ISampleApplication; 
gSampleApplication.Run; (run application) 

END 

ELSE 
StdAlert(phUnsuppor tedConf igurat ion); 
END. 


File USample.p: 
UNIT USample; 
INTERFACE 


USES 
UMacApp, UPrinting, UMAUtil, (MacApp Stuff) 
ToolUtils, Resources, Fonts, Packages, Printing; 


TYPE 
TSampleApplication = OBJECTCTApplication) 
PROCEDURE TSampleApplication.ISampleApplication; 
FUNCTION TSampleApp] ication .DoMakeDocument( 
itsCmdNumber: CmdNumber):TDocument; OVERRIDE; 
END; 


TSampleDocument = OBJECTCTDocument ) 
fDeviceCmd: Integer; 
fSampleView: TSampleView; 
PROCEDURE TSampleDocument.ISampleDocument; 
PROCEDURE TSampleDocument .DoMakeViews(forPrinting: 
BOOLEAN); OVERRIDE; 
PROCEDURE TSampleDocument .DoMakeWindows; OVERRIDE; 
PROCEDURE TSampleDocument .DoSetupMenus; OVERRIDE; 
FUNCTION TSampleDocument .DoMenuCommandCaCmdNumber : 
CmdNumber ) : TCommand; OVERRIDE; 


PROCEDURE TSampleDocument .SetCmd(CmdID: INTEGER); 
FUNCTION TSampleDocument.GetCmd: INTEGER; 
END; 


TSampleView = OBJECTCTView) 
fSampleDocument: TSampleDocument; 
PROCEDURE TSampleView.ISampleViewCitsDocument: TSample- 
Document); 
PROCEDURE TSampleView.DrawCarea: Rect); OVERRIDE; 


© The Best of MacTutor, Vol. 5 


END; 
IMPLEMENTATION 
($I ЏЅатр1е.іпс1.р) 
END. 
File USample.incl.p: 


CONST (private) 


kFileType = 422229; (File Type) 

kSignature = ‘Samx’; (Creator name) 
kSquareDots = TRUE; (for ImageWriter printer) 
kFixedSize = TRUE; 

kWindRsrcID = 1001; 

kPrinterStringID = 1001; (string resource ID} 
kMacStr ingID = 1002: (string resource ID} 


kFontStringId = 1003; 


(menu command number) 
(menu command number) 


cMac 
cPrinter 


VAR (private) 
hPos,vPos,Leading:Integer; (Used in Draw proc) 


2001; 
2002; 


($S AInit) 
PROCEDURE TSampleApplication.ISampleApplication; 
BEGIN 

SELF.IApplication(kFileTupe); 


) 


( ) 

($S AOpen) 

FUNCTION TSampleApplication.DoMakeDocument( 
itsCmdNumber: CmdNumber ): TDocument ; 

OVERRIDE; 


VAR 
aSampleDocument : 


BEGIN 
NEWCaSampleDocument); ^ (create document object) 
FailNilCaSampleDocument); (enough memory) 
aSampleDocument.ISampleDocument; (init doc object) 
DoMakeDocument := aSampleDocument; (result is doc) 
END; 


TSampleDocument ; 


( 

($S AOpen) 

m TSampleDocument . ISamp leDocunent ; 
GIN 
SELF .IDocument(kFileType, kSignature, kUsesDataFork, 

NOT kUsesRsrcFork, NOT kDataQpen, NOT kRsrcOpen); 

SELF .fSavePrintInfo := TRUE; (print record saved) 
SELF .fDeviceCmd:- cMac; 

END; 


( ) 
($8 A0pen) 
PROCEDURE TSempleDocument.DoMakeViewsCforPrinting: BOOLEAN); 
OVERRIDE; 
VAR 
aSampleView: TSampleView; 
aStdHandler: TStdPrintHandler; 


BEGIN 
NEWCaSamp leView); (create a view object) 
FailNilCaSampleView); (enough memory) 
aSampleView.ISampleViewCSELF); 
(pass doc that created this view) 
SELF .fSampleView :- aSampleView; 
(nost documents keep а reference to their views) 
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NewCaStdHandler ); (create a print handler) 
FailNILCaStdHandler); ^ (enough memory) 
aStdHandler.IStdPrintHandlerCSELF, aSampleView, NOT kSquare- 
Dots, kFixedSize, kFixedSize); 
END; 


( ) 
($5 AOpen} 
PROCEDURE TSampleDocument .DoMakeWindows; OVERRIDE; 
VAR 
aWindow: TWindow; 
BEGIN 
aWindow := NewSimpleWindow(kWindRsrcID, kWantHScrollBar, 
kWantVScrollBar, SELF, (doc) SELF.fSampleView2; (view) 
aWindow.SimpleStagger(kStdStaggerAmount, kStdStaggerAmount, 
gStdStaggerCount 2; 
END; 


( ) 
($S ARes) 
PROCEDURE TSampleDocument.DoSetupMenus; OVERRIDE; 
VAR 
SampleIndex: Integer; 
SampleCmd: Integer; 
BEGIN 
INHERITED DoSetupMenus; (alwaus do this) 
Enable(cMac, TRUE); 
Enable(cPrinter, TRUE); (enable this menu item) 
Samp leCmd:=SELF .GetCmd; 
FOR SampleIndex:=cMac TO cPrinter DO 
EnableCheck(SampleIndex, TRUE, (SampleIndex = SampleCmd)); 
END; 


( ) 
($S ARes) 
FUNCTION TSampleDocument .DoMenuCommand(aCmdNumber : 
CmdNumber ) : TCommand ; OVERRIDE; 
BEGIN 
DoMenuCommand := gNoChanges; (do this if not Undoable) 
CASE aCmdNumber OF 
cMac: 
BEGIN 
SELF .SetCmdCcMac?; 
SELF .f SampleView.ForceRedraw; 
(force update event for view) 
END; 
cPr inter: 
BEGIN 
SELF .SetCmdCcPr inter 2; 
SELF .f SampleView.ForceRedraw; 
END; 
OTHERWISE (always, so objects get a chance) 
DoMenuCommand := INHERITED DoMenuCommandCaCmdNumber ) ; 
END; (Case) 
END; 


( ) 
($S ARes) 
PROCEDURE TSampleDocument.SetCmdCCmdID: INTEGER); 
BEGIN 

SELF.fDeviceCmd := CmdID; (save string in doc var) 
END; 


—————————) 

($S ARes) 
FUNCTION TSampleDocument .GetCmd: Integer; 
BEGIN 


GetCmd := SELF.fDeviceCmd; (return vaiable as result} 
END; 


( 

($S AOpen) 

PROCEDURE TSampleView.ISampleViewCitsDocument: TSampleDocu- 
ment); 
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VAR 
itsSize: VPoint; 

BEGIN 
SetVPtCitsSize, 300, 300); (width, height: 32-bit numbers) 
SELF . IViewCitsDocument, (doc that created view) 


NIL, (superview) 

gZeroVPt, (topLef t) 

itsSize, (width, height as a VPoint) 
sizeFixed, (width) 


sizeFixed); (height) 
SELF .fSampleDocument := itsDocument; 
(save address of document in view) 
END; 


( ) 
($S ARes) 
E TSampleView.DrawCarea: Rect); OVERRIDE; 


PROCEDURE MyDrawStr ingCOutputStr:Str255); 
Begin 

DrawStr ing(OutputStr); 

vPos :=vPostLeading; 

MoveToChPos, vPos); 
End; 


(-------? 
PROCEDURE DrawMac; 
CONST 
envMaclIcx = 6; 
envSE30 = T;( Not in the MPW 3.0 interfaces ) 
VAR 
MyConf igRecord: ConfigRecord; (from MAUtil.p) 
Item: Integer; 
bItem: Boolean; 
Str: Str255; 
aString: Str255; 
aStr ingHd] : Str ingHandle; 
BEGIN 
aStringHd] := GetString(kMacStr ingID); 
FailNILResourceCaStr ingHd12; 
Str:-aStringHdl^^; 
MuDrawString(Str); 


Def ineConf iguration(MuConf igRecord); 
(from MAUtil.p) 


Item:= MyConf igRecord.environsVersion; 
NumToString(Item, Str); 
Str:= Concat( ^ environsVersion = ', Str ); 


MuDrawString(Str); 
CASE MyConf igRecord.machineType ОҒ 

envMac: 

aString := ‘Mac’; 
envXL : 

aString := ‘XL’; 
envMachUnknown: 

aString := ‘MachUnknown’; 
епу5 12КЕ: 

aString := ‘512KE’; 
envMacP lus: 

aString := ‘MacPlus’; 
envSE: 

aString := ‘SE’; 
envMacII: 

aString := 'MacII^"; 
envMacIIx: 

aString := ‘MacIIx’; 
envMacIIcx: 

aString := ‘MacIIcx’; 
envSE30 : 

aString := 'SE30'; 
OTHERWISE 


aString := 'MachUnknown'; 
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END; 


Str:= Concat(’ Machine Type = ' , aString); 
MuDrawString(Str); 


Item:= MyConf igRecord.systemVersion; 
NumToStringCItem, Str); 

Str:= ConcatC’ systemVersion = ' , Str); 
MyDrawStr ingCStr2; 


CASE MyConf igRecord.processor ОҒ 


envCPUUnknown : 

aString := 'CPUUnknown'; 
env68000 : 

aString :- ‘68020’; 
env689 10: 

aString := ‘68010’; 
епу68020: 

aString := ‘68020’; 
env68030 : 

aString :- '68030'; 
OTHERWISE 


astring := 'CPUUnknown'; 
END; 


Str:= ConcatC' CPU Version = ' , aString); 
MyDrawString(Str); 


bItem:= MyConf igRecord.hasFPU; 

IF bItem THEN Str:= ° has FPU = TRUE’ 
ELSE Str:= ' has FPU = FALSE’; 

MyDrawString(Str); 


bItem:- MyConf igRecord.hasColorQD; 

IF bItem THEN Str:= ' has Color QD = TRUE’ 
ELSE Str:= ' has Color QD = FALSE’; 

MyDrawStr ing(Str); 


CASE MyConf igRecord.keyboardType OF 
envUnknownKbd: 
aString := 'UnknownKbd'; 
envMacKbd: 
aString := ‘MacKbd’; 
envMacAndPad: 
astring := 'MacAndPad'; 
envMacP lusKbd: 
astring := 'MacPlusKbd'; 
envAExtendKbd: 
aString := ‘AExtendKbd’; 
envs tandADBKbd: 
astring := ‘StandADBKbd’; 
OTHERWISE 
astring := ‘UnknownKbd’ ; 
END; 


Str:= Concat(' Keyboard Type = ° , aString); 
MyDrawString(Str); 


Item:= MyConf igRecord.atDrvrVersNum; 
NumToString(Item, Str); 

Str:= Concat(’ Driver Version = ' , Str); 
MyDrawString(Str); 


Item:= MyConf igRecord.sysVRefNum; 
NumToStringCItem, Str); 

біг:- Concat(' System Ref Number = ' , Str); 
MyDrawString(Str); 


bI tem:= MyConf igRecord.hasROM 128K; 

IF bItem THEN Str:= ” has 128K ROM = TRUE’ 
ELSE Str:= ' has 128K ROM = FALSE’; 

MyDrawString(Str); 


bItem:= MyConf igRecord.hasHFS; 
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IF bItem THEN Str:= ' has HFS = TRUE’ 
ELSE Str:= ' has HFS = FALSE’; 
MyDrawString(Str); 


bItem:- MyConf igRecord.hasHierarchicalMenus; 

IF bItem THEN Str:= ' has Hierarchical Menus = TRUE’ 
ELSE Str:= ' has Hierarchical Menus = FALSE’; 

MyDrawString(Str); 


bItem:- MyConf igRecord.hasScr iptManager ; 

IF bi tem THEN Str:= ' has Script Manager = TRUE’ 
ELSE Str:= ‘ has Script Manager = FALSE’; 

MyDrawString(Str); 


bItem:- MyConf igRecord.hasStyleTextEdit; 

IF bItem THEN Str:= ' has StyleText Edit = TRUE’ 
ELSE Str:= ' has StyleTextEdit = FALSE’; 

MyDrawString(Str); 


bItem:- MyConf igRecord.hasSoundManager ; 

IF bItem THEN Str:= ' has Sound Manager = TRUE’ 
ELSE Str:= ‘ has Sound Manager = FALSE’; 

MyDrawStr ing(Str); 


bItem:- MyConf igRecord.hasWaitNextEvent; 

IF bItem THEN Str:= ' has WaitNextEvent = TRUE" 
ELSE Str:= ' has WaitNextEvent = FALSE’; 

MyDrawString(Str); 


bItem:- MyConf igRecord.hasSCSI; 

IF bItem THEN Str:= ' has SCSI = TRUE" 
ELSE Str:= ' has SCSI = FALSE’; 

MyDrawString(Str); 


bI tem:= MyConf igRecord.hasDesktopBus; 

IF bl tem THEN Str:= * has Desktop Bus = TRUE’ 
ELSE Str:= ' has Desktop Bus = FALSE’; 

MyDrawString(Str); 


END; 


ree 
PROCEDURE DrawPr inter ; 


TYPE 
PrGeneralPtr = “TGetRsIBlk; 
CONST 
GetRslData = 4; 
VAR 
aStringHdl:Str ingHandle; 
str: 5іг255; 
Item: LongInt; 


pDialog: PrGeneralPtr; 
i,NumberOfRecords: Integer; 
BEGIN 
aStringHdl := GetString(kPrinterStringID); 
FailNILResourceCaStr ingHd1); 
otr:-aStringHdl^^; 
MuDrawString(Str); 
pDialog:= PrGeneralPtr(NewPtrCSIZEOFCTGetRs1B1k22); 
PrOpen; 
IF PrError = noErr then 
BEGIN 
pDialog*. i0pCode:= GetRslData; 
PrGeneral(Ptr(pDialog)); 
IF PrError = noErr then 
BEGIN 
Number OfRecords:= pDialog^.iRslRecCnt; 
FOR i:= 1 to NumberOfRecords DO 
BEGIN 
Item :- pDialog* rgRsiRecl1].iXRs1; 
NumToString(Item, Str); 
Str:= Concat(' X Resolution = ° , Str); 
MuDrawString(Str); 
Item := pDialog* .rgRsiRec(1].iYRs1; 
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NumloString(Item, Str); 


Str:= ConcatC' Y Resolution = ° , Str); 


MuDrawString(Str); 
END; 
END 
ELSE 
BEGIN 
Item:= LongInt(PrError); 
NumToString(Item, Str); 
Str:= Concat(’ PrGeneral Error = ' , Str); 
MyDrawString(Str); 


BEGIN 
Item:= LongInt(PrError ); 
NumToStringCItem, Str); 
Str:= ConcatC' PrOpen Error = ° , Str); 
MyDrawString(Str); 
END; 
PrClose; 
IF PrError = noErr then 
BEGIN 
END 
ELSE 
BEGIN 
Item:= LongInt(PrError); 
NumToString(Item, Str); 
Str:= ConcatC' PrClose Error = ' , Str); 


MyDrawS tr ing(Str); 
END; 
END; 
( ) 
VAR 
itsQDExtent: Rect; 
Fontstr: Str255; 


FontNumber: Integer; 
aStringHdl: StringHandle; 
Mode: Integer; 
BEGIN 
PenNormal; (іп case someone else changed it) 
PenSizeC1, 1); 
PenPat(b lack ); 


SELF .GetQDExtentCitsQDExtent); (get size of this view) 
InsetRect(itsQDExtent, 2,2); 
FrameRect(itsQDExtent); (draw an enclosing rect) 


aStringHdl := GetString(kFontStr ingID); 
FailNILResourceCaStr ingHd1); 

FontStr := aStringHdl^^; (save string in variable} 
GetFNum(FontStr , FontNumber ); 


Tex tMode(srcOr ); 
TextFontCFontNumber 2; 
TextFace([ 12; 
hPos := 10; 

vPos :=32; 
MoveToChPos, vPos); 
TextSize( 12); 

Leading :=14; 


Mode :=SELF . f Samp leDocument .GetCmd; 
CASE Mode OF 
cMac: 
DrawMac; 
cPrinter: 
DrawPr inter ; 
OTHERWISE; 
END; 


Регћогта1; 
END; 
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File Sanples.r: 


®ifndef —MacAppTypes—— 
include “МасАррТурев.г” 
Rendif 


include “SysTypes.r” 


"if qDebug 

include "Debug.rsrc"; 
"endif 

include “MacApp.rsrc’; 
include “Printing.rsrc’; 


include “Sample? ‘CODE’; /* include CODE resources from 
compile/link */ 


/* cAboutApp, cNew, etc. defined in 
* (MARIncludes)MacAppTypes.r^ */ 
üdefine kWindRsrcID 1001 
define kPrinterStringID 1001 
define kMacStringID 1002 
"define kFontStringId 1003 
define сМас 2001  /* menu command number */ 
"define cPrinter 2002  /* menu command number */ 


/* SIR resource ID */ 
/* STR resource ID */ 


resource ‘vers’ (1) ( 

0x00, 0x95, beta, 0х2, verUS, 
“0 9502”, 

| “8.95 b2 (US), @1989 MacTutor” 


resource ‘vers’ (2) ( 
0х05, 0x08, development, 0х02, verUS, 
“Vol. 5 No. 8”, 
“MacTutor, Vol. 5 No. 8” 


Д 


resource ‘STR ' (kPrinterStringID) ( 
“This is the printer (Driver)”; 


д 


resource ‘STR * (kMacStringID) ( 
“This is the Mac’; 


7 


resource ‘STR ' (kFontStringID) ( 
“times”; 


2 


resource ‘cmnu’ (1) ( 
textMenuProc, 
@xTFFFFFFD, 
enabled, 


apple, 
( 


“About Sample..”, nolcon, noKey, noMark, plain, cAboutApp; 


*-^, nolcon, поКеу, noMark, plain, nocommand 
); 


resource 'cmnu^ (2) ( 
2 
textMenuProc, 
OxTFFFFBBB, 
enabled, 
“File”, 


“Кен”, nolcon, "N^, noMark, plain, cNew; 
“Ореп..”, nolcon, “0”, поМагк, plain, cOpen; 
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“-*, nolcon, noKeu, noMark, plain, nocommand; 
“Close”, nolcon, "W^, noMark, plain, cClose; 
“Save”, nolcon, “5”, noMark, plain, cSave; 

“Save As..”, noIcon, noKey, noMark, plain, cSaveAs; 


"Save a Copy In..”, noIcon, noKey, noMark, plain, cSave- 


Copy; 
*-*, nolcon, noKey, noMark, plain, nocommand; 


"Page Setup..”, noIcon, noKey, noMark, plain, cPageSetup; 


"Print One^, noIcon, noKey, noMark, plain, cPrintOne; 
“Print..”, noIcon, "P^, noMark, plain, cPrint; 

*-^, noIcon, поКеу, noMark, plain, nocommand; 

"Quit", noIcon, "Q^, noMark, plain, cQuit 


); 
resource 'cmnu^ (3) ( 


2 
textMenuProc, 
®x7FFFFFBD, 
enabled, 
“Edit”, 

( 


"Undo", nolcon, “7”, noMark, plain, cUndo; 
*-*, nolcon, поКеу, noMark, plain, nocommand; 
“Cut”, noIcon, "X^, noMark, plain, cCut; 
“Сору”, noIcon, “С”, noMark, plain, cCopy; 
“Paste”, noIcon, "V^, noMark, plain, cPaste; 
“Clear”, noIcon, поКеу, noMark, plain, cClear; 
*-*, noIcon, noKey, noMark, plain, nocommand; 


"Show Clipboard", noIcon, noKey, noMark, plain, cShowC1 ip- 


board 
); 
resource ‘cmnu’ (4) ( 


textMenuProc, 
Ox7FFFFFBD, 
enab led, 
“Sample”, 


"Query Mac”, noIcon, "M", noMark, plain, cMac; 
“-4, noIcon, noKey, noMark, plain, nocommand; 
"Query Printer’, noIcon, "P^, noMark, plain, cPrinter; 


X 


resource ‘MBAR’ (128) ( 
(1; 2; 3; 4) 


2 


resource ‘WIND’ (kWindRsrcID, purgeable) ( 
(50, 40, 375, 450), 
zoomDocProc, 
invisible, 
goAway, 
0x9, 
"((0»)»"^ 


); 


resource ‘SIZE’ (-1) ( 
saveScreen, 
acceptSuspendResumeEvents, 
enableOptionSwitch, 
canBackground, 
MultiFinderAware, 
backgroundAndForeground, 
dontGetFrontClicks, 
ignoreChildDiedEvents, 
1s32BitCompatible, 


reserved, reserved, reserved, reserved, reserved, reserved, 


reserved, 
#17 qDebug 
340 * 1024, 
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320 * 1024 
Üelse 

158 * 1024, 

120 * 1024 
"endif 


7 


resource ‘seg!’ (256, 
Sif qNames 

“Sample”, 

Sendif 

purgeable) ( 

( "GTerminate"; 
*GNonRes"; 
“GOpen’; 
“GWriteFile’; 
“GFile’; 
“GClose’; 
“0С1ірВоага”; 
*GDoCommand" ; 
^MAView"; 
*GSelCommand"; 

) 

Ji 


resource ‘mem!’ (256, 
Sif qNames 
“Sample”, 
üendif 
purgeable) ( 
43 * 1024,  /* Add to temporary reserve */ 
0, /* Add to permanent reserve */ 
0 /* Add to stack space */ 


2 


resource ‘DITL’ (201, purgeable) ( 
(/* array DITLarrau: 3 elements */ 
/* (1) */ 
(130, 182, 150, 262), 
Button ( 
enabled, 
“ОК” 
); 


/* [2] */ 

(10, 80, 110, 270), 

StaticText ( 
disabled, 
"This program queries the printer & Mac" 
“\n\nThis program was written ^ 


"with MacApp 2.8b9 € € 1985-1989 Apple Computer, Inc." 


); 
/* [3] */ 
(10, 20, 42, 52), 
Icon ( 
disabled, 
1 
) 
) 
n 


resource ‘ALRT’ (201, purgeable) ( 
(00, 100, 250, 412), 
(dd 


OK, visible, silent; 
OK, visible, silent; 
OK, visible, silent; 
OK, visible, silent 
) 
); 


==. 
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TechNotes 
New CDEF Messages 


System 7.0 will present all Macintosh programmers with 
new opportunities and new challenges. One of the challenges 
will be making your code 32-bit clean. This can be particularly 
difficult if your code uses parts of the Toolbox that are not 32-bit 
clean. Someof theroutines in the Control Manager, for example, 
are at best only 31-bit clean — that's close, but not close enough 
for System 7.0. This article will answer the challenge by 
explaining both the problem with, and the solution to, the Control 
Manager’s unclean habits. 

The specific problem that this article addresses lies in the 
calcCRgns CDEF message sent to all CDEFs. The message is 
sent to a control’s CDEF to calculate the control’s enclosing 
region, or the enclosing region of its indicator (if any). In Inside 
Macintosh [IM v1 p330], the calcCRgns CDEF message is 
explained as follows: “Param is a QuickDraw region handle. ... 
If the high-order bit of param is set, the region requested is that 
of the control's indicator rather than the control as a whole. The 
definition function should clear the high byte (not just the high 
bit) of the region handle before attempting to update the region." 

You can see that it's pretty hard to be 32-bit clean when 
you're supposed to go around clearing bytes in handles. The 
handle could contain a perfectly valid 32-bit address; clearing the 
high byte would change the address to something entirely differ- 
ent — and accessing or changing anything via that address would 
be a terrible mistake. Yet, it is required by the Control Manager, 
so what is a programmer to do? 

First, one can at least improve the situation by not clearing 
the whole high byte, as directed. Instead, just interrogate the high 
bit to see what region needs to be calculated, and then clear it — 
leaving the rest of the bits alone. This makes the code 31-bit 
clean; that's not good enough for System 7.0, but it'll do for the 
old systems. 

For System 7.0, Apple has defined two new CDEF mes- 
sages: calcCntIRgn (10) and calcThumbRgn (11). Instead of 
sending a calcCRgns message and having the CDEF figure out 
whether the system wants the control region or the indicator 
(thumb) region, the system will figure out which it wants, and 
send the CDEF the appropriate (new) message. The CDEF can 
then treat the region handle like a region handle, instead of like 
a secret message that has to be decoded. 

To make sure the world is a happy place, and that backward 
compatibility is maintained, a CDEF should always implement 
both the calcCRgns message and the new CDEF messages. That 
way, whether the CDEF finds itself in use under either System 7.0 
or a pre-7.0 system (which is pretty likely for the next year or 
two), it will respond in the manner the system expects. 

There are a couple of related issues. First, a control's 
variation code used to be stored in the high byte of the control 
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record's contrlDefProc field. To get the variation code, the 
programmer would mask it out of the high byte. This is unclean, 
since the contrlDefProc field may contain a valid 32-bit address. 
A new routine, GetCVariant(), was provided a couple of years 
ago (IM v5 p222) to return the control's variation code. Be sure 
to use it. 

Also, whenever writing custom CDEFs or/and other DEFs, 
remember that The Management Reserves the Right to Add New 
Messages at Any Time. Therefore, be sure that if your DEF 
receives a message it doesn't recognize, it just returns what it was 
given without doing anything (and without blowing up). 

Lastly, if you're going to add any custom messages to your 
custom DEF, set the new message numbers to constants greater 
than 128. This gives Apple the freedom it needs to add new 
messages, without tromping on your custom messages. 

That's about all the discussion this issue will bear. See the 
revision to Tech Note #212 for the official version of this same 
information. Below, I have appended the old, unclean 
calcCRgns implementation, the new and improved 31-bit clean 
calcCRgns implementation, and a shell CDEF entry-point func- 
tion that shows how all these messages should be handled. Note 
that the *param* actual argument is a valid handle to an empty 
region, so the content of the region indicated by param needs to 
be changed, not the value of param itself. You couldn't make any 
change to param stick anyway, since it's not a ‘var’ parameter 
(i.e., the CDEF gets a copy of param's value, not its address). 
Also, I'm assuming the existence of some routines, such as 
MyCalcThumbRgn() and MyCalcCtiRgn0, that are different for 
each different CDEF, and which are therefore not given here. 

I'd like to thank Andrew Shebanow, Larry Tesler, Charlie 
Oppenheimer, and Steve Goldberg at Apple — way to go, guys! 


(Qooooooooooooeoooooeoooeoeeeebooooooooooc epe eeCEEEOEE E E 


MyControl: Main entry point. Call appropriate 


message-handling routine. 
XXXXXXXXXXXX3X55X55X5XXXXX52X5X35XX5XX5X5X5X5XXXXX5XXXXXX) 


FUNCTION MuControl(varCode: INTEGER; 
theCnt1: ControlHandle; 
message: INTEGER; 
param: LONGINT): LONGINT; 


BEGIN 
MuControl := 0; ( default ) 
CASE nessage OF 
drawCnt]: 
doDrewOntlCtheCnt], varCode, param); 
testCntl: 
MyContro1 
initCntl: 
doInitOntlCtheCnt], varCode); 
dispCnt1: 
doDispCnt1(theCnt], varCode); 


‚= doTestOntlCtheCntl, param); 
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autoTrack: 
doAutoTrackCtheCnt]!, varCode, param); 


calcCRgns: ( support for рге-7.0 ) 
doCalcCRgnsNewCtheCnt], param); 

calcOntiRgn: (пен in System 7.0 ) 
MyCalcCtlRgnCtheCntl, RgnHandleCparam)); 

calcThumbRgn: ( пе ' in System 7.0 ) 
MyCalcThumbRgnCxheCntil, RgnHandleCparam)); 


OTHERWISE 
; ( ignore all other messages ) 
END; (cese) 
END; ( MyControl ) 


(ЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХАЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


doCalcCRgns0ld: Calculate the region the 
control or its indicator occupies in its 
window. Old method: Only 24-bit clean 
- don’t use this method anymore; use 


doCalcCRgnsNew(), below. 
XXXXXXKXKEXKXXXXKXXXKXXXXXXXXXXXXXXXKXXXXXXXXXXXXXXXXXXKXKD) 


PROCEDURE doCalcCRgnsOldCtheCntl: ControlHandle; 
param: LONGINT); 


BEGIN 
if (parem < 0) then ( high bit is sign bit ) 
begin 
( clear high BYTE and set thumb гоп } 
param := BitAnd(param, $ØFFFFFFF); 


else 
begin 
( clear high BYTE and set control rgn } 
param := BitAnd(param, $OFFFFFFF); 
MyCalcCtiRgnCtheCnt1, 
RgnHandle(param)); 


end; 
END; ( doCalcCRgnsOld ) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖХЖХЖХЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


doCalcCRgnsNew: New method: Only 31-bit 
clean, but that’s the best we can do. 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
PROCEDURE doCalcCRgnsNew( theCnt1: ControlHandle; 
param: LONGINT); 
BEGIN 
if (param < 0) then ( high bit is sign bit ) 
begin 
( clear high BIT and set thumb rgn ) 
param := BitAnd(param, $7FFFFFFF); 
MyCalcThumbRgn( theCnt1, RgnHandleCparam)); 
end 
else 
begin 
( clear high BIT and set control’s rgn } 
param := BitAnd(param, $7FFFFFFF); 
MyCalcCtiRgn( theCntl, RgnHandleCparam)); 
end; 
END; ( doCalcCRgnsNew ) 


MyCalcThumbRgnCtheCntl, RgnHandle(param)); e» 
end SEEDS 
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Pascal Procedures 
A Look At The PREC Resource 


As we all know the Apple ImageWriter printer has taken a 
back seat over the past several years to the LaserWriter. Most of 
us prefer Laser quality printing to that of the ImageWriter. 
However, another reality is the extra cost of the LaserWriter. 

A quick look back in history reminds us that there are some 
previsions in the Image Writer drivers which allow applications 
to “own” their own page sizes. This facility is brought to use by 
way of the PREC resource. In particular, the driver itself uses 
PREC resource ID=3 for the page size definitions as a default. If 
an application contains a PREC resource with ID=4 these size 
definitions take precedence. This may be old news to mostof us, 
but it doesn't seem to be well documented anywhere. The only 
place I found information about this was in some old notes from 
April, 1985. The Macintosh Technical notes don't give any 
indication about this subject. 

A sample RMaker source defining a PREC 4 resource that 
encodes the default configuration of the Page Setup Dialog is: 


Type PREC = GNRL 
*Paper size info - localizable, customizable. 
7 
mI 
XNumber of paper-size buttons used (max is 6): 
5 


*6 paper sizes іп 12@ths (decimal! ): 

*ist number is vertical, 2nd is horizontal. 
*First button: 8.5 X 11" ‘US letter’ paper 
1320 

1020 

*Second button: 8.25 X 11.66" ‘A4 letter’ 
1400 

990 

*Third button: 
1680 

1020 

*4th button:8.25 X 12" ‘international fanfold’ 
1440 

990 

*Fifth button: 14 X 11" 
1320 

1680 

XSixth button: - not visible 
0 

0 


8.5 X 14" “US legal” paper 


‘computer paper’ 


‚Р 
*Titles for six buttons. 
US Letter 
A4 Letter 
US Legal 
International Fanfold 
Computer Paper 
? 


*The blank line just above this one is necessary! 

One easy way of creating this type of resource is with 
RMaker. It may not be very convenient for non-programmers to 
create the resource without help. The Pascal application included 
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here allows editing and creation of the PREC 4 resource. Han- 
dling the resource is not too difficult although there are a couple 
of things you need to know to manipulate the structure. 

1. The type PREC is reserved for use by the Macintosh print 
driver. Itshould not be used in any other way than described here 
and not with any other resource ID other than 4. The PREC 3 
resource in the printer driver itself could be modified although is 
not recommended. 

2.Exactly six buttons must be defined in the PREC 4 
resource even if you are not using all the buttons. One character 
titles should be used for unused buttons. 

3. All PREC 4 numbers are in decimal. 

4. The first item in the PREC resource is the number of 
buttons to be displayed, a word-size integer. Whatever number 
is used here will be used by the printer driver to determine the 
number of items in the Page Setup dialog. If you use a number 
greater than six you are in big trouble. 

5. The dimensions follow next as an array of six pairs of 
integers. Each pair of numbers corresponds to the paper sizes 
with the first integer in each pair as the height and the second 
integer as the width. These numbers are given in 120ths of an 
inch. 

6. The remainder of the data is presented as an array of 
variable length Pascal strings. To getto each string, these strings 
need to be handled as a byte or char array. The first byte is the 
length of the first string which is followed by the first string, 
followed by the length of the second string, and so forth. 

Icredit my assistant, Prototyper for the shell of this program 
with the necessary additions added for loading, saving and 
manipulating the PREC 4 resource. The List Manager is used to 
display and select the 6 possible buttons. 

With all this said and done, it is good to note that Apple has 
announced that with System 7.0, spooling will be supported for 
all printers, not just the LaserWriter. Personally, I use the 
AppleTalk ImageWriter driver with 2 Macs wishing that the 
background printing was supported with the current system. 


ЕГЕ === PREC ERR 
Options File (by build order Size 
Runtime L ib S864 
Interface.lib 8104 
SANELib.lib 956 

R globa!s.p 

R FixMath.p 

R lInitTheMenus р 

R Aboutp 

R TEConvert p 

R Options.p 

R HandleTheMenus Pp 

R PREC4.p 


go 


| 


[N] 
alla 
ОЈ(А] 
[|D 
[D)[N] 
ON) 
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unit globals; 


interface 
var 
MyWindow: WindowPtr; (Window pointer} 
TitleFieldhndl: TEHandle; (Text Edit field handle) 
WidthFieldhndl: TEHandle; (Text Edit field handle) 
HeightFieldhndl: TEHandle; (Text Edit field handle) 
reply: SFReply; 
type 
realprec = record 
numberofbuttons: signedbyte; 
Size: errayg[1..61 of point; 
title: packed array(0..255] of char; 
end; 
realprec4ptr = ^realprec; 
realprec4hndl = ^realprec4ptr; 
prec = record 
numberofbuttons: integer; 
Size: array[1..6) of point; 
Title: array[1..6] of str255; 
end; 
prec4ptr = “prec; 
prec4hnd] = ^prec4ptr; 
var 
therealprec4: realprec; 
therealprec4hnd]: realprec4hnd!; 
prec4: prec; 
theprec4hndl: prec4hndl; 
implementation 
end. 


unit InitTheMenus; 

(File name: InitTheMenus.p} 

(Function: Pull in menu lists from а resource file.) 

( This procedure is called once at program start.) 

(  AppleMenu is the handle to the Apple menu, it is also) 
( used in the procedure that handles menu events.) 
(History: 6/10/89 Original by Prototyper.  ) 


interface 
procedure Init Му Menus; 
var 
AppleMenu:MenuHandle; ` (Menu handle) 
M File:MenuHandle; (Menu handle) 
M.Edit:MenuHandle; (Menu handle) 
implementation 
procedure Init Му Menus; (Initialize the menus) 
const 


(Initialize the menus) 


Menul = 1001; (Menu resource ID) 
Menu2 = 1002; (Menu resource ID) 
Menu3 = 1003; (Menu resource ID) 
begin (Start of Init_My_Menus} 
ClearMenuBar ; (Clear any old menu bars} 


AppleMenu := GetMenu(Menu1); (Get the menu) 
InsertMenu САрр1еМепи,@); (Insert this menur} 
AddResMenuCAppleMenu, ’DRVR’); (Add in DAs} 
MFile := GetMenu(Menu2); (Get the menu) 
InsertMenu (MFile,@); (Insert this menu) 
M_Edit := GetMenuC(Menu3); (Get the menu) 
InsertMenu (M.Edit,02; (Insert this menu) 


DrawMenuBar ; (Draw the menu bar) 
end; (End of procedure Init. My Menus) 
end. (End of this unit) 


unit About; 
(File name: About.p ) 
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(Function: Handle a dialog) 
(History: 6/10/89 Original by Prototyper.  ) 


interface 
procedure D. About; 
inplenentation 
const (These are item numbers for controls in the Dialog) 
I_OK = 1; 
Ix = 2; 
T_Icon6 = 3; 
var 
ExitDialog: boolean; (Flag used to exit the Dialog) 
DoubleClick: boolean; (Flag a double click on list) 
MyPt: Point; (Current list selection point} 
MyErr: OSErr; (05 error returned) 


function MyFilter CtheDialog: DialogPtr; var theEvent: 
EventRecord; var itemHit: integer): boolean; 
var 
tempRect: Rect; 
begin 
MyFilter := FALSE; 
if (theEvent.what = MouseDown) then(Only do on a mouse 
click) 
begin 
MyPt := theEvent.where; (Get the point where the mouse 
was clicked} 
Global ToLocal(MyPt); (Convert global to local) 
end; 


procedure D. About; 
var 
GetSelection: DialogPtr; (Pointer to this dialog) 
tempRect: Rect; (Temporary rectangle) 
ОТуре: Integer; (Туре of dialog item) 
Index: Integer; (For looping) 
DItem: Handle; (Handle to the dialog item) 
CItem, CTempItem: controlhandle; (Control handle) 
sTemp: Str255; (Get text entered, temp holding} 
itemHit: Integer; (Get selection} 
temp: Integer; (Get selection, temp holding) 
dataBounds: Rect; (Rect to setup the list} 
cSize: Point; (Pointer to a cell in a list) 
Icon Handle: Handle; (Temp handle to read an Icon into) 
NewMouse: Point; (Mouse loc during tracking Icon) 
InIcon: boolean; (Flag to say pressed in an Icon) 
ThisEditText: TEHandle; (Handle to get Dialogs TE rec) 
TheDialogPtr: DialogPeek; (Ptr to Dialogs definition 
record, contains the TE record) 
(This is an update routine for non-controls in the dialog) 
(This is executed after the dialog is uncovered by an alert) 
procedure Refresh Dialog; (Refresh dialogs non-controls) 
var 
rTempRect: Rect; (Temp rectangle used for drawing) 
begin 
SetPort(GetSelection); (Point to our dialog window) 
GetDItemCGetSelection, I.OK, DType, DItem, 
tempRect); (Get the item handle) 
PenSize(3, 3); (Change pen to draw default outline) 
InsetRectCtempRect, -4, -4); 
FrameRoundRect(tempRect, 16, 16); (Draw the outline) 
PenSizeC1, 1); (Restore pen size to the default value) 
end; 
begin (Start of dialog handler) 
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GetSelection := GetNewDialog(2, nil, Pointer(-1)); 
(Bring in the dialog resource) 
ShowWindowCGetSelection2; (Open a dialog box) 
SelectWindow(GetSelection); (Lets see it) 
SetPort(GetSelection); (Prepare to add conditional text) 
TheDialogPtr := DialogPeek(GetSelection); 
ThisEditText := TheDialogPtr^.textH; (Get to the TE record) 
HLockCHandleCThisEditText22; (Lock it for safety) 
ThisEditText^^.txSize := 12; (TE Point size) 
TextSize( 12); (Window Point size) 
ThisEditText^^.txFont := systemFont; (TE Font ID) 
TextFont(systemFont); (Window Font ID) 
ThisEditText^^.txFont := 0; (TE Font ID) 
ThisEditText^^.fontAscent := 12; (Font ascent} 
ThisEditText^^.lineHeight := 12 + 3 + 1; (Font ascent + 
descent + leading} 
HUnLockCHandleCThisEditText22; (UnLock handle when done} 
(Setup initial conditions) 
Refresh. Dialog; 
ExitDialog := FALSE; (Do not exit dialog handle loop yet) 
repeat (Start of dialog handle loop) 
ModalDialog(nil, itemHit); (Wait until an item is hit) 
GetDItemCGetSelection, itemHit, DType, DItem, 
tempRect); (Get item information) 
CItem := Pointer(DItem); (Get the control handle) 
(Handle it real time} 
if CItemHit = I_OK) then 


begin 
(?? Code to handle this button goes here) 
ExitDialog := TRUE; 
Refresh Dialog; 
end; (End for this item selected) 
if CItemHit = I Icon6) then(Handle the Icon) 
begin 
Icon-Handle := GetIcon( 10032); 


if CIcon_Handle © nil) then 
begin (Get ready to plot the hilighted icon) 
EraseRect(tempRect); (Erase the original icon) 
PlotIconCtempRect, Icon_Handle); 


end; (End of drawing hilighted icon) 
InIcon := TRUE; (Flag as mouse in the Icon) 
repeat (Start of mouse tracking routine) 


GetMouse(NewMouse); (Get latest mouse position) 
1f (PtInRect(NewMouse, tempRect)) then 
begin (...yes, over the Icon) 
1f not CInIcon) then 
begin(...yes, so it is unhilighted) 
Icon_Handle := GetIcon( 19032); 
if (Icon Handle © nil) then 
begin{...yes, have hilighted Icon) 
EraseRectCtempRect); 
PlotIconCtempRect, 
Icon_Handle); (Draw the hilighted icon) 
end; (End of Draw the hilighted icon) 
InIcon := TRUE; 
end; () 
end () 
else if InIcon then(Then draw unhilighted Icon) 
begin (Start drawing unhilighted Icon) 
Icon-Handle := GetIcon(32); 
if CIcon_Handle © nil) then 
begin(...yes, have hilighted Icon) 
EraseRect(tempRect); (Erase hilited icon) 
PlotIconCtempRect, Icon_Handle); (Draw 
the standard icon) 
end; (End of Draw the icon) 
InIcon := FALSE; 
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end; () 
until not CStillDown); 
if (PtInRectCNewMouse, tempRect)) then 
begin {...yes, released in the Icon) 
Refresh. Dialog; 
end; (End of released in the Icon) 
Icon-Handle := GetIcon(32); 
if CIcon_Handle © nil) then 
begin {...yes, have hilighted Icon) 
EraseRect(tempRect); (Erase the hilighted icon) 
PlotIconCtempRect, Icon_Handle); 
end; (End of Draw the icon) 
end; (End for this item selected} 
until ExitDialog; (Handle dialog items until exit} 
(Get results after dialog} 
DisposDialog(GetSelection); (Flush dialog out of memory) 
end; (End of procedure} 
end. (End of unit) 


unit TEConvert; 
(General utilities for conversion between TextEdit and 
strings} 
( see Macintosh Technical note 818 ) 
interface 
{ uses) 
( | MenTgpes, QuickDraw, OSIntf, ToolIntf;) 
procedure TERecToStr (hTE: TEHandle; var str: Str255); 
(TERecToStr converts the TextEdit record hTE to string str.) 
(If necessary, the text will be truncated to 255 characters.) 
procedure StrToTERec (str: Str255; hTE: TEHandle); 
(StrToTERec converts the string str to TextEdit record hTE. ) 
implementation 
procedure TERecToStr (ҺТЕ: TEHandle; var str: Str255); 
begin 
GetITextChTE^^.hText, str); 
end; 
procedure StrToTERec (str: Str255; hTE: TEHandle); 
begin 
TESetTextCPOINTERCORD4(@str) + 1), ORD4Clength(str)), 
ҺТЕ); 
end; 
end. 


unit Options; 
(File name: Options.p) 
(Function: Handle a Window) 
(History: 6/10/89 Original by Prototuper. ) 
interface 
uses 
globals, FixMath, TEConvert; 
procedure preparewidth Ci: integer); 
procedure prepareheight Ci: integer); 
procedure SetFields; 
procedure SetDefaultPREC; 
(Initialize us so all our routines can be activated) 
procedure Init Options; 
(Record status of all edit fields & buttons and update list) 
procedure Recordstatus; 
(Close our window) 
procedure Close Options (whichWindow: WindowPtr; var 
theInput: TEHandle); 
(Open our window and draw everything} 
procedure Open.Options (var theInput: TEHandle); 
(Update our window, someone uncovered a part of us) 
procedure Update. Options (whichWindow: WindowPtr ); 
(Handle action to our window, like controls) 
procedure Do Options (myEvent: EventRecord; var theInput: 
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TEHandle); 


implementation 
const 
TitleFieldid = 23; (Edit text ID) 
WidthFieldid = 24; (Edit text ID) 
HeightFieldid = 25; (Edit text ID) 
var 


tempRect, temp2Rect: Rect; (Temporary rectangle) 
Index: Integer; (For looping) 

CtrlHandle: ControlHandle; (Control handle) 

sTemp, sTempi: Str255; (Get text entered, temp holding) 
List I.Titles: ListHandle; (List Manager list handle) 
Rect I Titles: Rect; (List Manager list rectangle) 
dataBounds: Rect; (For use by lists) 

cSize: Point; (For use by lists) 

theRow: integer; (Used for adding rows to lists) 
num: extended; 

fixednum: Fixed; 

theCell: Cell; 


(=================================) 
procedure SetTeWidth (i: integer); 
begin 

num := PREC4.size[il.h / 120; 
fixednum := X2Fix(Cnum); 


NumToStringCHiWord(Fixednum), sTemp); 
num := (num - Hiword(Fixednum)) х 100; 
fixednum := X2FixCnum); 
NumToStr ingCHiWord(Fixednum), sTemp1); 
sTemp := concat(sTemp, ‘.’, sTemp1); 
TESetText(PointerCOrd4C8sTemp) + 1), length(sTemp), 
WidthF ieldhnd1); (Place default text in the TE area) 
SetRectCTempRect, 220, 82, 270, 
102); (left,top,right,bottom of WidthField Rectangle) 
TEUpdateCTempRect, WidthF ieldhndl2); 


end; 
(================s===========s===s===) 
procedure SetTeHeight Ci: integer); 
begin 
num := PREC4.size[il.v / 120; 
fixednum := X2Fix(num); 


NumloString(HiWord(Fixednum), sTemp); 
num := (num - Hiword(Fixednum)) * 100; 
fixednum := X2Fix(num); 
NumloString(HiWord(Fixednum), sTemp1); 
sTemp := concat(sTemp, ”.”, sTemp1); 
TESetText(Pointer(Ord4(@sTemp) + 1), length(sTemp), 

HeightFieldhnd1); (Place default text in the TE area) 
SetRect(TempRect, 326, 82, 376, 

102); (left, top,right,bottom of HeightField Rectangle) 
TEUpdateCTempRect, HeightF ieldhndl); 

end; 


procedure SetFields; 
var 
i, datalen: integer; 
begin 
for i := 6 downto 1 do 
begin 
dataLen := length(PREC4.Title[i12; 
cSize.v := i - 1; 
LSetCell(Pointer(ord(ePREC4.Title[i]) + 1), dataLen, 
cSize, List_I_Titles); (Set string in row ) 
LSetSelect(false, cSize, List_I_Titles); 
end; 
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SetTeWidthC 1); 

SetTeHeight( 1); 

TESetTextCPointerCOrd4CGPRECA4.TitleL 11) + 1), 
length(PREC4.Title[1]), TitleFieldnnd1); 

(default text in the TE area) 

SetRectCTempRect, 220, 40, 380, 62); 

TEUpdateCTempRect, TitleFieldhnd]); 

LSetSelect(true, cSize, List. I Titles); 


end; 
(========s===s=ss===================== 
procedure SetDefaultPREC; 
begin 
with prec4 do 
begin 
numberofbuttons := 5; 
Size(1].v := 1320; ( 11.0" ) 
Size[1].h := 1020: ( 8.50" ) 
Size[2].v := 1400; ( 11.66" } 
Size[2].h := 990; ( 8.25" ) 
Size[3].v := 1680; ( 14.0" ) 
Size[3].h := 1020; ( 8.50" ) 
Size[4].v := 1440; ( 14.0" ) 
Size[4].h := 990; ( 8.50" ) 
Size[5].v := 1320; ( 14.0" ) 
біге(51.Һ := 1680; ( 8.50" ) 
Sizel6].v := Ø; ( undef ined} 
Size[6].h := Ø; ( undef ined) 
Title[1] := ‘US Letter’; 
Title[2] := 'A4 Letter’; 
Title[3] := ‘US Legal’; 
Title[4] := ‘International Fanfold’; 
Title[5] := ‘Computer Paper’; 
Titlef6] := '?'; 
end, 
setF ields; 


SetWTitleCMyWindow, “Page Option Defaults’); 
end; 


(Initialize us so all our routines can be activated) 
procedure Init. Options; 
begin (Start of Window initialize routine) 
MyWindow :* nil; 
(Make sure other routines know we are not valid yet) 
end; (End of procedure) 


(Record status of all edit fields & buttons and update list) 
procedure Recordstatus; 
var 
i, datalen: integer; 
tempnumber: real; 
function strtox (s: str255): extended; 
var 
number: longint; 
total, multiplier: real; 


decimalposition, i: integer; 
begin 
total :- 0; 
decimalposition := posC'. ^, s); 


multiplier := 1; 
for i := (decimalposition - 1) downto ido 
begin 
stringtonumCs[i], number); 
total := total + (number * multiplier); 
multiplier := multiplier * 10; 
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end; 
multiplier := 0.1; 
for i := (decimalposition + 1) to length(s) do 
begin 
stringtonum(s[i], number); 
total := total + (number * multiplier); 
multiplier := multiplier / 10; 


end; 
1f decimalposition = 0 then 
begin 
multiplier := 1; 
total := 0; 
for i := length(s) downto 1 do 
begin 
stringtonum(s[i], number); 
total := total + (number * multiplier); 
multiplier := multiplier * 10; 
end; 
end; 
strtox := total; 
end; 
begin 
Csize.h := 0; 


TERecToStr(CTitleFieldhndl, sTemp); 

PREC4.Title[cSize.v + 1] := sTemp; 

dataLen := length(sTemp); 

LSetCel1(PointerCord(@sTemp) + 1), dataLen, cSize, 
List_I_Titles); (Set string in row } 

TERecToStr(WidthFieldhndl, sTemp); 

i := 120; 

tempnumber := strtox(sTemp) * i; 

PREC4.size[cSize.v + 1].h := truncCtempnumber ); 

TERecToStrCHeightF ieldhndl, sTemp1); 

tempnumber := strtox(sTempl) * i; 

PREC4.size[cSize.v + 1].v := trunc(tempnumber); 

end; 


(Close our window) 
procedure Close.Options; 
begin (Start of Window close routine) 


if (MyWindow © nil) and ((MuWindow = whichWindow) or 


Cord4CwhichWindow) = -1)) then 
begin 

if CtheInput = TitleFieldhndl) then 
theInput := nil; (Clear the handle used) 

if (theInput = WidthFieldhndl) then 
theInput := nil; (Clear the handle used) 

if CtheInput = HeightFieldhndl) then 
theInput := nil; (Clear the handle used) 


DisposeW indow(MyWindow); (Clear window and controls) 


MuWindow := nil; 
end; (End for if (MyWindowOni1)) 
end; (End of procedure) 


(Update our window, someone uncovered a part of us) 
procedure UpDate. Options; 
var 


SavePort: WindowPtr; (Place to save the last port) 


sTemp: Str255; (Temporary string) 
begin (Start of Window update routine) 
Recordstatus; 
if (MyWindow O nil) and (MyWindow = whichWindow) 
then(Handle an open when already opened) 
begin 
GetPort(SavePort); (Save the current port) 
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Se tPor tCMyWindow); (Set the port to my window) 
TextFont(systemFont); (Set the font to draw in) 
(Draw a string of text, ) 

setRect(tempRect, 273, 85, 318, 102); 

sTemp := '““ X^; 

TextBox(PointerCord(@sTemp) + 1), length(sTemp), 

tempRect, teJustLef t2; 
TextFontCapplFont); (Set default application font) 


TextFont(systemFont); (Set the font to draw in) 
(Draw a string of text, ) 
SetRect(tempRect, 378, 85, 423, 102); 
sTemp := '*': 
TextBoxCPointerCord(ésTemp) + 1), length(sTemp), 
tempRect, teJustLef t); 
TextFontCapplFont?; 
(Update a TE box, US Letter ) 
setRect(TempRect, 220, 40, 380, 
65); (left,top,right,bottom) 
FrameRect(TempRect); (Frame this TE area) 
InsetRect(TempRect, 3, 3); (Surround the TE area) 
if (TitleFieldhnd] o nil) then 
begin (Update the TE area) 
TEUpdateCTempRect, TitleFieldhndl); 
(Update the TE area) 
TextFontCapplFont); 
(Set the default application font) 
end; (End of the TE area) 
(Update & TE box, Width ) 
SetRectCTempRect, 220, 82, 270, 102); 
FrameRect(TempRect); (Frame this TE area) 
InsetRect(TempRect, 3, 3); (Surround the TE area) 
if (WidthFieldhnd] o nil) then( 
begin (Update the TE area) 
TEUpdeteCTempRect, WidthFieldhndl); 
(Update the TE area) 
TextFontCapplFont); 
(Set the default application font) 
end; (End of the TE aree) 
(Update a TE box, Height ) 
SetRectCTempRect, 326, 82, 376, 192); 
FrameRect(TempRect); (Frame this TE area) 
InsetRect(TempRect, 3, 3); (Surround the TE area) 
if (HeightFieldhndl o nil) then 
begin (Update the TE area) 
TEUpdateCTempRect, HeightF ieldhndl2); 
(Update the TE area) 
TextFontCsystemFont); 
(Set the default application font) 
end; (End of the TE area) 
(Update a List, Titles ) 
SetRect(TempRect, 21, 21, 204, 117); 
TempRect.Right := TempRect.Right - 15; 
(Go inside the scroll bar) 


InsetRectCTempRect, -1, -1); (Surround the List area) 


FrameRect(TempRect); (Frame this List area) 
if (List I Titles © nil) then 
LUpdateCMuW indow^ .visRgn, List. I Titles); 
DrawControls(MyWindow); (Draw all the controls) 
SetPort(SavePort); (Restore the old port) 
end; (End for 1f (MyWindowOoni12) 
end; (End of procedure) 


(Open our window and draw everything) 
procedure Open. Options; 
var 
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Index: Integer; (For looping) TitleFieldhndl := TENew(TempRect, TempRect); 


dataBounds: Rect; (For making lists) if (thelnput © nil) then 

cSize: Point; (For making lists) TEDeactivate(theInput); (Yes, so turn it off) 

(This is a routine used to add strings to an existing list) theInput := TitleFieldhnd!; (Activate the TE area) 
procedure Add List String CtheString: Str255; theList: HLockCHandleCTi tleFieldhndl2); 
ListHandle); TitleFieldhndl^^.txFont := systemFont; 

var TitleFieldhndl^^.fontAscent := 12; (Font ascent) 
theRow: integer; (The Row that we are adding) TitleFieldhndl^^.lineHeight := 12 + 3 + 1; 

begin HUnLockCHandleCT i tleF ieldhnd12); 

if (theList © nil) then sTemp := ‘US Letter’; 
begin TESetTextCPointerCOrd4CésTemp) + 1), length(sTemp), 

cSize.h := Ø; (Point to the correct column} TitleFieldhnd1); (Place default text in the TE area) 
theRow := LAddRow(1, 200, theList); TEActivateCTitleFieldhndl2; (Make the TE area active) 
cSize.v := theRow; (Point to the row just added) TEUpdate(TempRect, TitleFieldhnd1); 
sTemp := theString; (Get the string to add) TextFont(app]Font); 
LSetCell(Pointer(ord(ësTemp) + 1), length(sTemp), (Make a List, Titles ) 
cSize, theList);(Place string in row just created) SetRect(TempRect, 21, 21, 204, 
LDraw(cSize, theList); (Draw the new string) 117); (left, top, right, bottom) 
end; Rect_I_Titles := tempRect; (Save the list position} 
end; TempRect Right := TempRect.Right - 15; (бо inside the 
begin (Start of Window open routine} scroll bar area) 
if (MyWindow = nil) then InsetRectCTempRect, -1, -1); (Surround the List area) 
begin FrameRect(TempRect); (Frame this List area) 
MyWindow := GetNewWindowC1, nil, Pointer(-1)); InsetRect(TempRect, 1, 1); (Restore to the List area) 
SetPort(MyWindow); (Prepare to write into window) SetRect(dataBounds, 0, 0, 1, 0); (Make the empty list) 

(Open a TE box, Width ) cSize.h :- TempRect.Right - TempRect.Left; 
SetRect(TempRect, 220, 82, 270, 102); (Get the width of the list) 
FrameRect(TempRect);(Frame this TE area) cSize.v := 16; (Set the HEIGHT of each list element) 
InsetRect(TempRect, 3, 3); (Restore the original size) List_I_Titles := LNew(TempRect, dataBounds, cSize, 0, 
WidthFieldhnd] := TENew(TempRect, TempRect); MyWindow, TRUE, FALSE, FALSE, TRUE); (Create the list) 
1f CtheInput © nil) then List I Titles^^.selFlags := lOnlyOne + 

TEDeactivate(theInput); (Yes, so turn it off) INONiTHilite; (Set for only one active item at a time) 
theInput := WidthFieldhndl; (Activate the TE area) LdoDrawCTRUE, List. I Titles); (Draw list) 
HLockCHandleCWidthF ieldhnd12); cSize.h := 0; (Point to correct col, starts at zero) 
WidthFieldhndl^^.txFont := systemFont; Add. List. StringC'US Letter’, List I Titles); 
WidthFieldhndl^^.fontAscent := 12; (Font ascent) Add.L ist. StringC'A4 Letter’, List I Titles); 
WidthFieldhndl^^.lineHeight := 12 + 3 + 1; Add_List_String(€‘US Legal’, List_I_Titles); 
HUnLockCHandleCWidthF ieldhnd] )); Add_List_String( ‘International Fanfold’, 
sTemp := ‘8.50’; List_I_Titles); 

TESetText(Pointer(Ord4(@sTemp) + 1), lengthCsTemp), Add_List_String( ‘Computer Paper’, List. I Titles); 
WidthFieldhndl); (Place default text in the TE area) Add_List_String(‘?’, List I Titles); 
TEActivateCWidthF ieldhndl); cSize.h := 0; {All elements are in column 0) 
TEUpdate(TempRect, WidthFieldhndl); cSize.v := 0; (Select the first list element) 
TextFontCapplFont); LSetSelectCTRUE, cSize, List I Titles); 

(Open a TE box, Height ) ShowWindow(MyWindow); (Show the window now) 
SetRect(TempRect, 326, 82, 376, 102); SelectWindow(MyWindow); (Bring our window to the 
FrameRect(TempRect); (Frame this TE area) front) 

InsetRect(TempRect, 3, 3); (Restore the original size) SetDef aultPrec; 
HeightFieldhndl := TENew(TempRect, TempRect); end (End for if CMyWindow<>nil)} 
if CtheInput © nil) then else 

TEDeactivateCtheInput2; (Yes, so turn it off) SelectWindow(MyWindow); (Already open, so show it) 
theInput := HeightFieldhndl; (Activate the TE area) end; (End of procedure) 
HLockCHandleCHe ightF ieldhndl2); 

HeightF ieldhndl TE txFont 'z systemFont ; (==========s==================s=s===s=) 

HeightF ieldhndl^^.fontAscent := 12; (Font ascent} (Handle action to our window, like controls) 

HeightFieldhndl^^.lineHeight := 12 + 3 + 1; procedure Do_Options; 

HUnLock(Handle(HeightFiel]dhnd1)); var 

sTemp := '11.0'; RefCon: longint; (RefCon for controls) 

TESetText(Pointer(Ord4(@sTemp) + 1), length(sTemp), code: integer; (Location of event in window or controls) 
HeightFieldhndl); (Place default text in the TE area) theValue: integer; (Current value of a control) 

TEActivateCHeightFieldhndl2; (Маке the TE area active) whichWindow: WindowPtr; 

TEUpdateCTempRect, HeightF ieldhndl); myPt: Point; (Point where event happened) 

TextFontCapplFont); theControl: ControlHandle; (Handle for a control) 

(Open a TE box, Title ) MyErr: OSErr; (0S error returned) 
SetRect(TempRect, 220, 40, 380, 62); DoubleClick: boolean; (Used bu lists) 
FrameRect(TempRect);(Frame this TE area) datalen: integer; 

InsetRect(TempRect, 3, 3); (Restore the original size) begin (Start of Window handler} 


© The Best of MacTutor, Vol. 5 425 


Recordstatus; 
if (MyWindow © nil) then 
begin 
code := FindWindow(myEvent.where, whichWindow); 
1f CmyEvent.what = MouseDown) and (MyWindow = 
whichWindow) then() 
begin 
myPt := myEvent.where; (Get mouse position) 
with MyWindow^.portBits.bounds do 


begin 
myPt.h := myPt.h + left; 
myPt.v := myPt.v + top; 
end; 


SetRect(tempRect, 220, 40, 380, 62); 
і? PtInRect(myPt, tempRect) then 
begin 
if CtheInput © nil) then 
TEDeact ivateCtheInput?); 
theInput := TitleFieldhnd!; 
TEActivateCtheInput2; (Turn it on) 
TEClickCmyPt, FALSE, TitleFieldhnd1); 
end; 
SetRect(tempRect, 220, 82, 270, 102); 
if PtInRect(myPt, tempRect) then 
begin 
1f CtheInput © nil) then 
TEDeact ivateCtheInput?; 
theInput := WidthFieldhnd!; 
TEActivateCtheInput2; (Turn it on) 
TEClick(myPt, FALSE, WidthFieldhnd1); 
end; 
SetRectCtempRect, 326, 82, 376, 102); 
if PtInRect(mgPt, tempRect) then 
begin 
if (thelnput © nil) then 
TEDeactivate(theInput); 
thelnput := HeightFieldhndl; 
TEActivate(theInput); (Turn it on) 
TEClick(myPt, FALSE, HeightFieldhndl); 
end; 
1f PtInRect(myPt, Rect_I Titles) then 
begin 
DoubleClick := LClick(myPt, 
myEvent modifiers, List_I_Titles); 
1f DoubleClick then 
begin 
end; 
begin 
cSize := LLastClick(List_I_Titles); 
datalen := 100; 
LGetCell(PointerCord(@sTemp) + 1), 
dataLen, cSize, List_I_Titles); (Get string in row ) 
1f not (LGetSelect(false, cSize, 
List_I_Titles)) then 


begin 
theCell.v := 0; 
theCell.h := Ø; 


д 
if LGetSelect(true, theCell, 
List_I_Titles) then 
begin 
cSize := theCell; 
detalen := 100; 
LGetCel1CPointerCord(@sTemp) + 
1), dataLen, cSize, List_I_Titles); (Get string in row } 
end; 
end; 


426 


TESetText (Pointer (Ord4C@PREC4 .Title(cSize.v + 1]) + 1), 
dataLen, TitleFieldhndl); 

SetRect(TempRect, 220, 40, 380, 62); 

TEUpdateCTempRect, TitleFieldhndl5; 

setTeWidth(cSize.v + 1); 

SetTeHeight(cSize.v + 1); 

end; 
end; 
end; 


if (MyWindow = whichWindow) and (code = inContent) 
then(for our window) 
begin 
code := FindControl(myPt, whichWindow, 
theControl); (Get type of control} 
if (code © 0) then(Check type of control) 


code := TrackControlCtheControl, myPt, 
nil); (Track the control) 


end; (End for 1f CMyWindow=whichW indow)) 
end; (End for if (MyWindowOni12) 
end; (End of procedure) 
(======================s=s======s==s==) 
end. (End of unit) 


unit HandleTheMenus; 
(File name : HandleTheMenus.Pp ) 
(Function: Handle all menu selections.) 
( This procedure is called when a menu item is selected.) 
( There is one CASE statement for all Lists. There is) 
( another CASE for all the commands in each List.) 
(Historu: 6/10/89 Original bu Prototuper. ) 
( Created for MacTutor ) 
( ©1989 CopyRight MacTutor All Rights Reserved ) 
interface 
uses 
Globals, About, Options, InitTheMenus; 
procedure Handle_Mu_Menu (var doneFlag: boolean; theMenu, 
theItem: integer; var theInput: TEHandle); 
implementation 
procedure Handle_My_Menu; 
const 
L_Apple = 1001; (Menu list} 
C_About_Page_Sizes = 1; 
LFile = 1002; (Menu list} 


C_Open = 1; 
C_Save_As = 2; 
C-Set Page.Setup. Default = 4; 
C_Quit = 6; 
L.Edit = 1003; (Menu list) 
C_Undo = 1; 
C_Cut = 3; 
С_Сору = 4; 
C-Peste = 5; 
var 


DNA, Err: integer; (For opening DAs) 
BoolHolder: boolean; (For SystemEdit result) 
DAName: Str255; (For getting DA name) 
SavePort: GrafPtr; (Save current port when opening DAs} 
where: point; (1ocation of SF dialogs) 
prompt, origname, astring: str255; 
typeList: SFTypeL ist; 
numtypes, count, oldcount: integer; 
Total_length, RefNum, i, j, k: integer; 
PRECHndl, SaveHndl, hndl: handle; 

begin (Start of procedure) 

case theMenu of (Do selected menu list) 
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L_Apple: 
begin 
case theltem of 
C_About_Page_Sizes: 
begin 
D_About; (Call a dialog) 
end; 
otherwise (Handle the DAs} 
begin(Start of Otherwise) 
GetPort(SavePort); (Save the current port) 
GetItemCAppleMenu, theItem, DAName); 
(Get the name of the DA selected) 
DNA := OpenDeskAcc(DAName ); 
SetPort(SavePort); (Restore to saved port} 
end; (End of Otherwise} 
end; (End of item case) 
end; (End for this list) 


L_File: 
begin 
case theltem of 
C_Open: 
begin 
(Call the SFGetFile 05 routine) 
where.h := 80; 


where.v := 80; 

prompt := '^; 

numTypes := -1; 

SFGetFileCwhere, prompt, nil, numTypes, 
typeList, nil, reply); 

if reply.good = true then 

begin 
RefNum := OpenRFPerm(reply.fName, 

reply.VRefNum, 3); 


1f (RefNum = -1) or (ResError © NoErr) 


then 
se tDef aul tPrec 
else 
begin 
Count := CountResources( ‘PREC’ ); 
if Count = 0 then 
SetdefaultPrec 
else 
begin 
UseResF i leCRefNum); 
PRECHndl := 
Get IResource( ‘PREC’, 4); 


if (PRECHndl = nil) or CResEr- 


ror © NoErr) then 
SetdefaultPrec 
else 
begin 
HNoPurgeCPRECHnd1 2; 
therealprec4hndl := 
realprec4hndl(PRECHnd!2; 
fork := 1 to 6 do 
begin 
PREC4.Size[k).h : 


therealprec4hndl^^.Size[k].h; 


PREC4.Sizelk].v : 
therealprec4hndl^^.Size(k].v; 


end; 
count := -1; 
fork := 1 to 6 do 
begin 


count := count + 1; 


ordCtherealprec4hndl^^.title[count]) - 1; 
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count := count + 1; 
oldcount := count; 
PREC4.Title[k] := “2; 
for count := oldcount 
to oldcount + j do 
begin 
PREC4.Title[k] := 
concəat(PREC4.Title[k], therealprec4hndl1**.title[count]); 
end; 
1f PREC4.Title[k] 


then 
PREC4.Title[k] := 
97. 
count := oldcount + j; 
end; 
SetWTitle(MuWindow, 
replu.fName); 
end; 

CloseResFile(RefNum); 

HPurge(PRF-Hndl1); 

DisposHandie(PRECHnd1); 

SetFields; 

end; 
end; 
end; 
end; 
C_Save_As: 
begin 
(Call the SFPutFile 0S routine) 
where.h := 80; 


where.v := 80; 

origname := reply.fName; 

prompt := ‘Save PREC4 resource to file:’; 
SFPutFileCwhere, prompt, origName, nil, 


reply); 
1f reply.good then 
begin 
Total_length := 32; (first half of PREC 
resource} 


for i := 1 to 6 do 
Total_length := Total_length + 
lengthCPREC4.Titlelil); 
SeveHndl := NewHandle(CTotal. length); 
(Create new PREC resource) 
14 SaveHnd] <> nil then 
begin 
HNoPurge(SaveHndl2; 
therealprec4Hndl := 
realprec4hndl(SeveHnd12); 
therealprec4hndl^^ .numberofbuttons 
:= 0; 
for i := 1 to 6 do 
if ClengthCPREC4.Titlelil) о 0) 
or (PREC4.Titleli] = '?^) then 


therealprec4hndl^^.numberofbuttons := 
therealprec4hndl^^.numberofbuttons + 1; 
for к := 1 to 6 do 
begin 
therealprec4hndl^^.Sizelk).h : 


PREC4.Sizelk].h; 


therealprec4hndl^^.Sizelk].v : 
PREC4.Sizelk].v; 
end; 
if lengthCPRECA.Title( 11) О 0 then 
astring := PREC4.Title[1] 
else 
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astring := concat(chr(1), “27; 
for j := 2 to 6 do 
begin 
1f lengthCPREC4 .Title[jl) «© Ø 
then 
astring := concatCastring, 
chr(length(PREC4.Title[j1)), PREC4.Title(j]) 
else 
estring := concatCastring, 
chr 1), '?/); 
end; 
therealprec4hnd1**.Title(@] := 
chr ClengthCPREC4.Titlel[1])); 
for i := 1 to lengthCastring) do 
begin 
therealprec4hnd]**.Titleli] := 
astringlil; 


end; 
err := SetVol(nil, reply. VRefNum); 
err := CreateCreply. fname, 


reply.vRefNum, ‘PROF’, ‘TEXT’); 
CreateResF ileCreply. fname); 
1f ResError = dupFNErr then 
begin 
RefNum := 
OpenRfPermCreply.fname, reply.VRefNum, 3); 
hndl := Get IResource( ‘PREC’, 
4); 
if Hnd] © nil then 
begin 
RmveResource(Hnd] ); 
ChangedResource(Hnd1); 
UpdateResFile(RefNum); 
DisposHandleCHnd1); 
end; 
end; 
begin 
RefNum := OpenRfPerm(reply.fname, 
reply.VRefNum, 3); 
end; 
addresource(SaveHndl, ‘PREC’, 4, 
у; 
writeresource(saveHnd1); 
closeresf i leCRef Num); 
HPurge(SaveHnd] 2; 
DisposHandle(SaveHndl); 
SetWTitleCMyWindow, reply.fName); 
end; 
end; 
end; 
C Set Page. Setup. Default: 
begin 
SetDefaul tPREC; 
end; 
C_Quit: 
begin 
doneFlag := TRUE; 
end; 
otherwise 
begin(Start of the Otherwise) 
end; (End of Otherwise) 
end; (End of item case} 
end; (End for this list) 
L-Edit: 
begin 
BoolHolder := SystemEditCtheItem - 1); 
if not (BoolHolder) then 
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begin (Handle by using a Case statment} 
case theltem of 

C_Undo: 
begin 
end; 

C_Cut: 
begin 
end; 

C_Copy: 
begin 
end; 

C_Paste: 
begin 
end; 

otherwise(Send to a DA} 
begin(Start of the Otherwise} 
end; (End of Otherwise} 

end; (End of not BoolHolder) 
end; (End of item case) 
end; (End for this list) 


otherwise 
begin (Start of the Otherwise) 
end; (End of Otherwise) 
end; (End for the Lists) 
HiliteMenuC0); (Turn menu selection off) 
end; (End of procedure Handle. My Menu) 
end. (End of unit) 
(The Project should have the following files in it: ) 


(uRunT ime.1ib LSP This is for main Pascal runtime library) 


( Interface.lib LSP This is the Mac trap interfaces) 
( InitTheMenus.p This initializes the Menus.) 

( About Modal Dialog) 

( Options Window) 

( HandleTheMenus Handle the menu selections.) 


(Set RUN OPTIONS to use the resource file PREC4.RSRC ) 
( RMaker file to use is PREC4.R ) 

(  PREC4.p Main program ) 

program PREC4; 

(Program name: PREC4.p ) 

(Function: This is the main module for this program. ) 
(Historu: 6/10/89 Original bu Prototuper. ) 

( Created for MacTutor ) 

( @1989 CopyRight MacTutor A11 Rights Reserved ) 


uses 
globals, About, Options, InitTheMenus, HandleTheMenus; 
var (Main variables) 


myEvent: EventRecord; 
doneFlag: boolean; (Exit program flag) 

code: integer; (Determine event tupe) 
whichWindow: WindowPtr; (See which window for event) 
tempRect, OldRect: Rect; (Rect for dragging) 

mResult: longint; 

theMenu, theItem: integer; (Menu list and item selected) 
chCode: integer; (Key code) 

ch: char; (Key pressed in Ascii) 

theInput: TEHandle; (Used in text edit selections) 
myPt: Point; (Temp Point, used in Zoom} 


(Event record for all events} 


begin (Start of main body) 
MoreMasters; (This reserves space for more handles) 
InitGraf CéthePort); (Quickdraw Init) 
InitFonts; (Font manager init) 
InitWindows; (Window manager init) 
InitMenus; (Menu manager init) 
TEInit; (Text edit init) 
InitDialogs(nil); (Dialog manager) 
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FlushEvents(everuEvent, 0); (Clear out all events) 


InitCursor; (Make an arrow cursor) 

doneFlag := FALSE; (Do not exit program yet) 
Init.My. Menus; (Initialize menu bar) 

theInput := nil; (Init to no text edit selection active) 
Init Options; (Initialize the window routines) 


Open_Options(theInput); (Open window routines) 
D_About; (Open the modal dialog routines at program start) 
reply.fname := ”” | 
repeat (Start of main event loop) 
1f (thelnput O nil) then(See if a TE is active) 
TEIdleCtheInput); 
SystemTask; (For support of desk accessories} 
if GetNextEventCeveryEvent, myEvent) then 
begin (Start handling the event} 
code := FindWindow(myEvent.where, whichWindow); 
case myEvent what of (Decide type of event) 
MouseDown: {Mouse button pressed) 
begin (Handle the pressed button} 
if (code = inMenuBar) then 
begin(Get the menu selection and handle it) 


mResult := MenuSelect(myEvent . Where); 
theMenu := HiWord(mResult); 
theItem := LoWord(mResult); 


Handle_My_Menu(CdoneF lag, theMenu, thel tem, 
theInput); (Handle the menu} 
end; (End of inMenuBar) 
1f (code = InDrag) then 
begin(Do dragging the window) 
tempRect := screenbits.bounds; 
SetRect(tempRect, tempRect.Left + 10, 
tempRect.Top + 25, tempRect.Right - 10, tempRect.Bottom - 10); 
DragWindow(whichWindow, muEvent.where, 
tempRect); (Drag the window) 
end; (End of InDrag) 
if (Ccode = inGrow) and (whichWindow © nil)) 
then(In a grow area of the window) 
begin(Handle the growing) 
SetPortCwhichWindow); 
myPt := myEvent.where; (Get mouse position) 
GlobalToLocal(myPt); (Make it relative) 
OldRect := WhichWindow^ .portRect; 
with screenbits.bounds do(screens size) 
SetRect(tempRect, 15, 15, (right - 
left), (bottom - top) - 20); (1, t,r,b) 
mResult := GrowWindow(whichWindow, 
myEvent.where, tempRect); (Grow it) 
SizeWindow(whichWindow, LoWord(mResult), 
HiWord(mResult), TRUE); (Resize to result) 
SetPor tCwhichWindow); 
SetRectCtempRect, Ø, myPt.v - 15, myPt.h + 
15, myPt.v + 15); (Position for horz scrollbar area) 
EraseRect(tempRect); (Erase old area) 
InvalRect(tempRect); (Flag us to update it) 
SetRectCtempRect, myPt.h - 15, 0, myPt.h + 
(Position for vert scrollbar area) 
EraseRect(tempRect); (Erase old area) 
InvalRect(tempRect); (Flag us to update it) 
DrawGrowIcon(whichWindow?); 
end; (End of doing the growing) 
if (code = inZoomIn) or (code = inZoomOut) 
then (Handle Zooming windows) 
begin() 
14 CWhichWindow O nil) then 
Бедіп() 
SetPort(whichWindow); 
myPt := muEvent.where; 


15, myPt.v + 15); 
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GlobalToLocal(myPt); (Маке it relative) 
OldRect := whichWindow^ .portRect; 
if TrackBoxCwhichWindow, myPt, code) 
then(Zoom it) 
begin() 
ZoomWindow(WhichWindow, code, 
TRUE); (Resize to result) 
SetRectCtempRect, 0, 0, 32000, 
32000); 
EraseRect(tempRect); 
InvalRect(tempRect); 
end; 
end; 
end; 
if (code = inGoAwau) then 
begin(Handle the goawau button) 
1f TrackGoAwau(whichWindow, muEvent.where) 
then(See if mouse released in GoAwau box) 
begin(Handle the GoAwau) 
case (GetWRef ConCwhichWindow2) of 
I: 
begin 
Close .Options(whichWindow, 
theInput); (Close this window) 
doneFlag := TRUE; 
end; 
otherwise(Handle others dialogs) 
begin(Others) 
end; (End of the otherwise) 
end; (End of the case) 
end; (End of ТгаскбоАнау) 
end; (End of ІпбоАнау) 
if (code = inContent) then 
begin(Handle the hit inside a window) 
if (whichWindow O FrontWindow) then 
SelectWindowCwhichWindow) 
else 
begin(Handle the button in the content) 
SetPor tCwhichWindow); 
case (GetWRefConCwhichWindow)) of 
12 
Do_Options(muEvent, 
theInput); (Handle this window) 
otherwise(Handle others dialogs) 
begin(0Others) 
end; (End of the otherwise) 
end; (End of the case) 
end; (End of else) 
end; (End of inContent) 
1f (code = inSysWindow) then 
SystemClickC(myEvent, whichWindow); 
end; (End of MouseDown) 
KeyDown, AutoKey: (Handle key inputs) 
begin (Get the key and handle it) 
with myevent do(Check for menu command keys) 
begin() 
chCode := BitAnd(message, 
CharCodeMask); (Get character) 
ch := CHRCchCode2; (Change to ASCII} 
if (Odd(modif iers div CmdKey)) then 


begin() 
mResult := MenuKeu(ch); 
theMenu := HiWord(mResult); 
theItem := LoWord(mResult); 


if (theMenu ‹ 0) then 
Handle_My_Menu(doneF lag, theMenu, 
theItem, theInput); (Do the menu selection) 
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1f (Cch = “x?) or (ch = °X’)) and 
(thelnput © nil) then() 


TECut(theInput); 
if (Cch = ‘c’) or (ch 
(thelnput © nil) then() 


'C^)) and 


TECopyC the Input ); 
if ((ch = ‘v’) or (ch = ‘V’)) and 
(theInput © nil) then() 
TEPaste( theInput); 
end() 
else if (theInput © nil) then( 
begin 
1f ch = chr(9) then 
begin 
TEDeact ivateCtheInput?; 
if theInput = TitleFieldhndl 
then 
theInput := WidthFieldhndl 
else if theInput = 
WidthFieldhndl then 
theInput := HeightFieldhndl 
else if theInput = 
HeightFieldhndl then 
theInput := TitleFieldhndl; 
TEActivateCtheInput2; (Turn it on) 
recordstatus; 
end 
else 
TEKeyCch, theInput); () 
end; 
end; () 
end; (End for KeyDown, AutoKey) 
UpDateEvt: ^ (Update event for a window) 
begin (Handle the update) 
whichWindow := WindowPtr(mgEvent message); 
BeginUpdateCwhichWindow); 
case (GetWRefConCwhichWindow)) of 
1: 
Update Options(whichWindow); 
otherwise (Handle others dialogs) 
begin (Others) 
end; (End of the otherwise) 
end; (End of the case) 
EndUpdate(Cwh ichWindow); 
end; (End of UpDateEvt) 
DiskEvt: (Disk inserted event) 
begin (Handle a disk event) 
1f CHiWord(myevent.message) € noErr) then 
begin(due to unformatted diskette inserted) 
myEvent .where.h := 
(Cscreenbits.bounds.Right - screenbits.bounds.Left) div 2) - 
(304 div 22; (Center horz) 
| muEvent.where.v := 
((screenbits.bounds.Bottom - screenbits.bounds.Top) div 3) - 
(104 div 2); (Тор 3ed vertically) 
InitCursor; (Make sure has arrow cursor) 
chCode := DIBadMount(myEvent . where, 
myevent .message); (Let the 0S handle the diskette) 
end; 
end; (End of DiskEvt) 
app IEvt: 
begin (Start handling our events) 
if (HiWord(myEvent.message) = 1) and 
CLoWord(myEvent .Message) = 1) then 
Open_Options(theInput); (Open the window) 
1f CHiWord(myEvent .message) = 2) and 
CLoWord(myEvent .Message) = 1) then 
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Close Options(WindowPtrCord4C- 12), 
theInput); (Close the window) 
end; (End handling our events) 
ActivateEvt: (Window activated event) 
begin (Handle the activation) 
whichWindow := WindowPtr(myevent message); 
1f odd(myEvent . modif iers) then 
begin(Handle the activate) 
SelectWindow(whichWindow2; 
end; (End of Activate) 
end; (End of ActivateEvt) 


otherwise 
end; (End of case) 
end; (end of GetNextEvent) 
until doneFlag; (End of the event loop) 
end. (End of the program) 


2222929292929222222222292222922922999 999922929 929 2929 9 29 292 9 29 29 9 9 ХХХ 


RMaker resource file sources. 
File: PREC4.R 


History: 6/10/89 Original by Prototuper. 
This file contains the sources for all the resources except 


for Pictures. 
x 


$22222922292292222222229222222229929 29 2229292 2292 22 2 9 22 0 9222221 


ы жым м 


PREC4.RSRC 
APPL???? 
x 
Tgpe WIND 
,1 ;,Resource ID 
Page Setup Options ;,Window title 
45 20 185 454 ;; Top Left Bottom Right 
InVisible GoAway ;, Visible GoAwau 
16 ;;ProcID, Window def ID 
1 ;;Refcon, reference value 
Type DLOG 
x 
22 ;,Resource ID 
About ;;Dialog title 
51 54 182 355 Тор Left Bottom Right 
Visible NoGoAway } Visible GoAway 
l ;;ProcID, dialog def ID 
2 ;;Refcon, reference value 
2 ;,;1D of item list 
Type DITL 
x 
‚2 ;;Resource ID 
3 ;;Number of controls in list 


Button Enabled ; Push button 
99 109 120 189 ;,lop Left Bottom Right 
OK ; message 


StaticText ;;Static text 

30 80 90 280 ;;Top Left Bottom Right 
ImageWriter Page Size EditorN0D0@1989 MacTutorNODBu Dave 
Kellu;;message 


Icon Enabled 
4 32 72 64 


;;Icon 
;;lop Left Bottom Right 
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31 ;;ID for the resource to use, Icon6 


Type ICON = GNRL 


* This Icon is Icon6 
‚32 ;;ICON Resource ID 

.H 

00000000 001C0000 003Е0000 007F8000 
00ҒҒЕ000 Q1FFF800 OS3FFFCOO 0ТҒВҒС00 
@7FEF800 OS3FFBOOD 017ҒҒ800 02 1ҒҒ400 
02Е79200 02011700 0200 1200 0200 1700 
02809200 02ҒҒ09000 0277176С 01002254 
00804254 001Ғ8000 00408000 0078000 
01806000 06001800 086 18400 130С3200 
10000200 1FFFFE00 00000000 00000000 
‚1 


000C6000 0006C000 00038000 00010000 


ll 


` Type MENU 
x 


, 1001 
\14 
About Page Sizes... 


Open.../0 
Save As../S 
(- 


Set Page Setup Defau 


(- 


; Resource ID 
;; APPLE menu title 
;;item title 


;;Resource ID 
тели title 
;;ltem title 
ніс title 


j) 
lt ;;item title 
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, 10032 ;;ICON highlighted Resource ID Quit/Q ;;item title 
.H 
00000000 00010000 00038000 0006C000 , 1003 ;,Resource ID 
00006000 00 188000 00370800 006ҒЕС00 Edit телу title 
000ҒҒ600 O1BFFBOO 037FFD80 O6FFFECÓ (Undo/Z ;;item title 
@DFFFF60 1BFFFFBO 37FFFFD8 6FFFFFEC (- 24 
FIFFFFDE 73FFFF9C 31FFFF18 18FFFE3@ Cut /X ;;item title 
ЙСТЕҒС60 063FF8C0 031FF180 018ҒЕЗ00 Copy/C ;;item title pod! 
00СТС600 00638C00 00311800 00183000 Paste/V ;;item title тт 
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MacApp Workshop 


A Tale of Two Quadratic Plotters 


[Author’ s Note: This article is NOT about MacA pp. We do 
not cover the basics which you can get elsewhere. For example, 
this article does not discuss the concepts behind Object program- 
ming and Object Pascal syntax, nor do we explain the organiza- 
tion of all the MacApp classes. The December 1987 MacTutor, 
Kurt Schmucker' s excellent book Object Oriented Programming 
for the Macintosh, the January 1989 APDALog, the newsletter 
of the MacApp Developer’ s Association (Frameworks ) or the 
MacApp documentation itself are good reference sources. You 
may understand some of this article without knowing the basics 
behind Object Pascal or MacApp, but don't count on it! The 
programs discussed in this article were written using MacApp 
2.008. By the time this is published, the final MacApp 2.0 should 
be available. As far as we know, no changes to this code should 
be necessary to compile, link, and run it under the final version 
of MacApp 2.0, but one never knows...] 


Introduction 

This article is about the conversion of Dave Kelly's and 
Dave Smith's Plot Program into a MacApp program. The 
program originally appeared as part of the Multifinder Friendly 
MacDraw Plotter article in the February 1988 MacTutor. Actu- 
ally, we will discuss two conversions, one written by Chuck 
McMath (this month) which attempts to literally translate the 
original program into MacApp and the other a conversion (next 
month), by Carl Nelson, ports the intent of the original program 
into a MacApp program. We review the original article and 
program, then expose the mechanics and decisions involved in 
doing both conversions. Along the way, we will show you the 
basics of physically creating a MacApp program and give you 
some of our reasoning and insight as to why we did what we did. 
Hopefully you can use this wisdom to do the same as you start 
writing programs using MacApp. Most of us using MacApp have 
learned "the hard way" - hours of working on projects until we 
reach ‘enlightment’ on the techniques needed to take advantage 
of object programming languages. 

The motive of this article is not to present the blinding vision 
of enlightenment on how to learn MacApp but rather a pragmatic 
approach, an exploration of two ways that might work. We know 
the starting point (the original program) and the ending point (the 
original program rewritten using MacApp). Let’s travel along 
the path from start to end with two programs, one a simple clean 
translation and the other a program that produces the same effect 
but is internally quite different — the low road (direct translation) 
and the high road (conversion and expansion). Two points of 
view, and two results. From both of these you can gain insight 
into the mechanics of MacApp and a brief look at how Objects 
and MacApp change the way you look at writing programs. 
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Chuck McMath 


үші; Carl Nelson 
— MacApp Developer's Assoc. 
MPW Pascal Volume 5, Number 8 


Introduction Revisited 

While Carl's viewpoint is the elegance and power that 
MacApp gives you in terms of code reusability, my perspective 
is somewhat different. The main impression that I had when I 
looked at the “Multifinder Friendly Plotter’ was “hey — this 
program is all user-interface." Although it does spend some time 
solving a quadratic equation and fooling around with picture 
comments, most of the code is involved with the plot parameters 
dialog box, putting the window up, handling events correctly, 
etc. Of course, you might say those features are necessary in any 
Macintosh program, right? Absolutely! These ‘common user 
interface' features are what MacApp is all about. My point of 
view is that MacApp provides a full-blown user interface, 
freeing you from having to worry about those details, and letting 
you concentrate on what makes your application different. You 
can turn your application out more quickly, and have it be of 
higher quality and greaterreliability. The bottom line: less work! 

I took the design of the plotter application and decided to 
implement it just as it was. I didn't make any changes to the 
overall design to take advantage of MacApp, but (and this is an 
important but) I also did not limit the program to take away any 
of MacApp's benefits. For instance, the original plotter program 
puts up a dialog box, waits for you to enter parameters, and then 
plots the quadratic equation in a new window. If you replot the 
equation, you get a plot in the same window — i.e., only one 
window is on the screen at a time. MacApp, however, imple- 
ments multiple windows as a given; instead of throwing out 
MacApp's multiple window feature, I allowed the new plotter 
application to take advantage of that capability. The result is that 
the new plotter application allows you to produce as many plot 
windows as memory allows — and better yet — this was done 
with very little work on my part. 


The Original Program 

The original plotting program was written just after the new 
Macintosh ROMs became widely available. Since MacTutor 
likes to keep on the cutting edge, the two Daves decided to write 
a program which implements as many features as they could 
cram into a coherent whole. While the explicit purpose of the 
program is to solve quadratic equations, the real purpose was to 
showcase some of the new features in the Mac ][/SE ROMs. The 


new features being exhibited included: 

- calling SysEnvirons to determine if the machine supported 
the required new features 

- resources to specify colors in menus/windows 

- hierarchical menus used to select colors for parts of the 
plot 

- Multifinder support through calling WaitNextEvent and 
acting on Multifinder events 

- capability to save plots es PICT files, and the use of 
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PicComments to group logicallu related items 
- hairlines on the LaserWriter through using PicComments. 


The operation of the program is fairly simple: when Plot is 
selected from the File menu, a modal dialog box appears. The 
user types numbers in for the quadratic equation parameters and 
some plot parameters, then clicks the OK button (there is no 
Cancel button). The dialog goes away, and a plot window 
appears, with the solution to the quadratic equation plotted in the 
window. The plot is sized so as to always fill the entire window 
(minus allowance for the scroll bars, of course). A Graph menu 
lets the user change the color of the axis, the plot, and the 
background items. A Print Options menu allows the user to 
specify whether the printed output should be actual size (i.e., the 
window size) or a full page size. The Graph menu features three 
hierarchical menus displaying the colors which may be chosen 
for the three elements of the plot which can be colored (the axes, 
the plot itself, and the background). The colors available are the 
8 supported in the so-called ‘Old QuickDraw model.’ The 
window can be resized, dragged, zoomed, and closed. The 
contents of the window may be saved, and if saved, the file 
written out is a PICT file which can be opened in MacDraw. If 
the file is opened in MacDraw, individual items can be manipu- 
lated, as if the plot were drawn in MacDraw itself. Selecting Plot 
again while a plot window is up brings up the modal dialog again, 
but when it is dismissed, the plot is redrawn in the existing 
window (only one window is allowed on the screen). 

This is only an overview of the original program and this 
short description cannot do it justice. If you’d like to go read the 
original article, we won’t be offended (just come back to this 
one.) And now, back to Carl. 


MacApp Provides Features 

As Chuck said, the original article and program were written 
to show new features introduced into the Macintosh environment 
in early 1988 and not as the best or even the right way to do 
plotting of equations. The original article and the example 
program show a style for teaching and exploring programming. 
In order to accomplish their task, the two Daves drew sourcecode 
from Professional Programmers Extender, past issues of Mac- 
Tutor, Dave Wilson’s Examples and Steve Sheet’s Code, Inside 
Macintosh, and по less than 13 Apple Tech Notes. Several times 
in the article you can find a Dave saying: “It is much faster to cut 
and paste source code from someone else, than to reinvent the 
wheel yourself.” The theme of this article, and many MacTutor 
articles, could just as well have been learning through reuse and 
extension. Programming by extending and reusing code is one 
of premises of an application framework and a key feature of 
languages containing Objects. We show how reuse and exten- 
sion can occur when bringing the MacTutor Plot program into the 
MacApp framework. Writing thisa year later and having version 
2.088 of MacApp in hand, many of the concerns presented in the 
article are non-issues. To be specific: 

* Update Events & Growing the Window 

MacApp users in general (and specifically for a program the 
size and complexity of Plot) never worry about update events. 
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The MacApp architecture nicely handles setting things up for 
you so that all you have to do is draw when asked to by MacApp. 
MacApp programmers seldom worry about events, the event 
loop, Desk Accessories or switching in and out under Multifin- 
der. There is a very robust event handling architecture provided 
by MacApp and it has been our experience that as the MacOS 
changes, Apple has enhanced MacApp to match the changes. 

e Multifinder 

Being Multifinder friendly and having to deal with Wait- 
NextEvent are non-issues. MacApp properly handles all of it as 
long as the ‘SIZE’ resource is properly set up. If background 
processing is needed the right objects should be overridden. 

* Palette Manager 

The MacApp DrawShapes Example program provides us 
with an example of how to setup a custom Palette color with a 
single call to the toolbox GetColor routine. 

* Menus (Color, hierarchical or otherwise) 

MacApp has a very interesting and useful scheme for han- 
dling menus and the actions to be taken when menu selections are 
made. MacApp uses aresource named ‘cmnu’ which is the same 
as a regular ‘MENU’ but adds an integer to the end. This integer 
serves as a unique command number for that entry. The cmnu 
resources are post-processed by a utility called PostRez. It splits 
apart cmnus and creates a regular MENU and a table that maps 
these command numbers to menu items for use in your program. 
MacApp uses these unique command numbers to inform you of 
menu selections as well as handling the standard kind of menu 
functions like New, Open and Save. Command numbers 0 
through 1200 are reserved for use by MacApp; the rest are 
available for use in your program. The nice side effect of this is 
that you can rearrange menus without regard to where they reside 
in the MENU BAR or their item number. All you ever deal with 
is the unique command number. Of course there are good 
examples of custom Menus in both the MacApp Developer’s 
Association ‘Goodies Disk’ and the MacApp samples shipped by 
Apple. 

° Saving 

MacApp provides all the code surrounding New, Save and 
Save As. Ifallof your data fits into memory at once, you will have 
to implement only two procedures, DoNeedDiskSpace and 
DoWrite, to save your data. You donot have to worry about temp 
files, disk space and errors, as MacApp provides a powerful error 
handling mechanism to handle general case failures so you do not 
have to. 

* Printing 

By creating a standard print handler object and assigning it 
to a view (objects which display things in MacApp) a view can 
be made can be made to print as well as display on the screen. 
Because of this mechanism, you usually do not have to worry if 
you are drawing to the screen or a printer port. 

* Machine/System Determination 

MacApp provides compile time variables (qNeedsS- 
criptManager, qNeedsROMI128K, qNeedsHierarchialMenus, 
qNeedsStyleTextEdit, qNeedsWaitNextEvent, qNeedsCol- 
orQD, qNeedsMC68020, qNeedsMC68030, qNeedsFPU) that 
you can use to configure your application so that if your 
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combination of features is not present, your application will 
safely exit. 

With all of the above support, I will not dwell on these 
features of MacApp [Chuck s note: I will dwell on them to some 
extent.]. We will take this support as given and refer to them as 
appropriate in our discussions of our conversions. Again, you 
can find ample documentation as to how these work by reading 
the MacApp 2.0 final documentation, browsing the sources 
which are supplied with MacApp or looking through the 1988 
and 1989 issues of Frameworks which discuss the MacApp 2.0 
Architecture. 

With all this out of the way we can move on to discuss our 
conversion efforts. Chuck gets to go first and discuss his efforts 
then I will talk about my conversion. 


Overall Program Design 

The crucial point of creating a MacApp program comes 
before any code has been written: design is the key, for if you 
have a good object design the code becomes obvious (well, if not 
‘obvious,’ then maybe ‘more clear’). A good design can be 
understood by many people. A bad design is usually not even 
understood by its creator after a short time passes. The major 
design of our objects is easy. This is because we are using 
MacApp. By using MacApp, you ‘sign a pact’ to become a 
member of the MacApp community. This agreement says that 
you will accept all of the wonderful features MacApp provides 
for your application; in exchange, you agree to be a good citizen 
and write your application according to a particular structure. 
This structure enables you to take advantage of the MacApp 
code, and in a sense, drop your code into MacApp and have it 
work. The difficult part of object design is deciding where the 
things you are familiar with fitin. When you start out, you will 
often be asking yourself which feature and parameters belong to 
which object. As we'll see, determining this is usually easy, once 
you understand the objects MacApp provides for us, and how 
they relate to the pieces of your application. In this particular 
case, the design is made easier in that we are simply converting 
an existing program to MacApp, and I am following the original 
design as much as possible. This means that many of the 
decisions have been made for us. 

MacApp has a number of predefined object classes which 
equate to the different portions of an application. These prede- 
fined objects have the ‘generic Mac thing’ behavior already 
implemented. For instance, there is an object which corresponds 
to the overall application — TApplication (incidentally, 
MacApp object types all begin with a capital T. Thisis, suppose, 
to remind you that an object is simply a declared type in Pascal). 
An object of type TApplication ‘knows’ how to do all of the 
things that a good application must — handle desk accessories, 
put up an about box, work under MultiFinder, launch when 
double-clicked upon in the Finder, open a document when the 
documentis double-clicked, etc. Therefore, you don't have to do 
anything to your application to have it exhibit this behavior. 
Instead, you worry about the part of your application that is 
different from a standard application. One aspect of MacApp 
programming that you will become accustomed to is that you 
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don't do all of the work — you let MacApp do it for you. This 
can make you somewhat confused, for in many cases, you only 
implement a few methods for an object — yet it seems to be quite 
a sophisticated object. This is because you are taking advantage 
of the predefined MacApp object behavior. Don't worry, you 
will quickly get used to not doing all of the work yourself — and 
you might even like it. 


MacApp Function Subclass 


TApplication | Manages Documents TOPlotApplication 


launch, open, etc. 


holds data 
stored on disk 


TDocument TQPlotDocument 


TView TQPlotView 


Displays data in 
windows 


Table 1: MacApp Objects and QPlot 
Descendents 


Table 1 shows a simplified description of the predefined 
MacApp objects, what they are responsible for, and the descen- 
dent objects defined in the plotter application. Keep in mind that 
when you define an object and modify its behavior, you can be 
doing one of two things: adding some behavior that does not 
exist, or changing some existing behavior. Our TQPlotApplica- 
tion is an example object which was created for both of these 
reasons. Behavior has to be added to it to handle the colorful 
hierarchical menus, for example. And some behavior also has to 
be changed — and this is where experience with MacApp 
becomes necessary — because the generic MacApp behavior of 
an application is to open a blank document when you 
double-click on the application in the Finder. In our case, this 
behavior is not what we want to happen, so, I decided to override 
the method which produces the blank document. This requires 
*behavior modification' for our TApplication object. 

AS you can see from the table, this application requires only 
a few simple objects (remember, my goal was to do a quick 
conversion and not to make the application into the ultimate 
MacApp program). There is, of course, an application object, 
since every MacApp program has to have an application object 
— TQPlotApplication. There is a document, since we are 
concerned with storing data on the disk — TQPlotDocument. 
There is a view, since we are displaying data in a window — 
TQPlotView. And, last, but not least, there is the dialog view, 
since we have a dialog which requests the plot parameters — 
TDialog View. Note that the dialog view is nota specialized view 
we defined. Why is that? Well, when you look at whata typical 
Macintosh dialog view lets you do, you will realize that 
MacApp’s dialog functions are ample to do what we want, 
especially since our dialog is a simple one. The other objects, 
though, warrant some explanation to show what they provide 
outside of the generic MacApp structure. Which leads us to the 
question: 
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How does anything get done? 

Good question, Chuck! Things get done in MacApp by 
having one of the conceptual“control chains’ take over. The 
most prevalent ‘chain’ used in MacApp is the inheritance chain. 
Many parts of MacApp use this sort of chain to pass control on 
from child (subclass) to parent (superclass). Knowing where to 
hook in by OVERRIDE ing is the key to using this and the other 
chains. The other chains are: 

1) The command chain routes system generated events to 
objects that want to handle them. 

2) The idle chain is traversed during idle to give selected 
objects periodic chances to execute. 

3) The choice chain informs a view object's parent views 
that its state has changed. 

Knowing these chains exist help you to determine where as 
wellas who does the work and gives you conceptual frameworks 
around which to build your application. Now what were you 
going to say about the plotter application, Chuck? 

In the plotter application, nothing happens unless the user 
selects something using the mouse, so we will only consider 
mouse down events, which are part of the command chain 
(incidentally, you don't need to know much about these ‘chains’ 
in order to program in MacApp, although knowing what is goin g 
on under the hood helps you to understand when things turn out 
differently from what you expect. But back to mouse downs...) 
In addition, I'll classify the mouse downs into either menu bar 
hits or ‘other.’ Initially I will discuss menu bar hits and how you 
translate from a menu selection to some activity. 

In a non-MacApp program menu enabling and disabling is 
tied quite closely in with activate and deactivate events. Of 
course, this makes perfect sense, because when you activate a 
window you want that window's menu items enabled, and vice 
versa when the window is being deactivated. There are a few 
inherent problems with this approach, however. First, you need 
to have special code in your activate or deactivate event handling 
procedure to eat up successive activate/deactivate events (the 
way Chernikoff's MiniEdit does it) or else you will end up in the 
wrong state — with the wrong items enabled. Second, this 
technique is not easy to extend or modify, and if you end up 
adding a new window type, then you add volumes to the code. 


MacApp and Menus 

In MacApp, menus are handled quite differently, as Carl has 
described above. MacApp tries to ‘unhook’ the connection 
betweenan item in a menu and an object which handles that item. 
Instead of hard-coding menu processing ina gigantic procedure, 
MacApp introduces the concept of commands and command 
numbers. Think of each menu item as representing a different 
command, and each command having its unique number. Some 
commands will best be handled by the application — New, Open, 
and Quit for example. Other command are the domain of the 
document — Save, SaveAs and Close. Still other commands 
should be handled by the object which draws the data — turning 
grids onand off, aligning objects, perhaps cutting and pasting. So 
you can see that instead of a central processing repository for all 
‘menu actions,” MacApp farms the commands out the different 
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objects. In fact, this is a crucial tenet of object programming: ап 
object will only deal with information it knows how to process. 


. Therefore, in MacApp, each object is given a stab at a menu 


selection. If the object ‘knows’ how to handle that command, it 
does whatever it is supposed to. If, however, the object doesn't 
recognize that command as something it knows about, the object 
just passes the request along. Eventually either some object 
somewhere handled the menu choice, or MacApp senses that no 
object handled the menu choice, and that choice is simply thrown 
away. 

Menu enabling is handled in the same distributed way as 
menu selection: there is a special method defined for objects in 
MacApp where they enable or disable the menu items they are - 
concerned with. This ensures your program will never see a 
menu item enabled if it shouldn't be, because the only way that 
item is enabled is if its corresponding object exists. In fact, 
whenever MacApp determines that the menu bar could have 
changed, it disables every item in all of the menus. Only after all 
items have been disabled do the individual existing Objects get a 
chance to enable their functions. 


Using a Command to Do Work 

When a selection is made from a menu, the object that 
chooses to handle the menu selection can do one of two things: 
go ahead and perform whatever action was called for (in easy or 
trivial cases), or create a command object to perform the com- 
mand and pass it back to MacApp to be executed (more difficult 
cases). Command objects are the technique MacApp uses to 
implement an action and its associated Undo and Redo. Since all 
of the actions in the plotting program were simple and could be 
undone easily, my version of the plotter application does not have 
any command objects. [Carl’s Note: My version does] 

What about mouse downs that aren't in the menu bar? They 
are normally handled by a method called DoMouseCommand 
(pretty obvious name, eh? Most MacApp methods attempt to be 
as obvious) but since the plotter application is a simple one, we 
don't have anything to do in this method. All of the normal 
Macintosh behavior is already provided for us by MacApp: 
dragging the window around; clicking and dragging in the grow 
box, and resizing the window when we release the button; 
clicking in the close box to indicate that we want to put the 
window away; clicking in the zoom box to zoom or unzoom the 
window — all of these normal, everyday Macintosh features are 
there — yet we didn't do a thing about them. This is the power 
of MacApp. 


The Application Object 

The application object, as we have mentioned before, is 
responsible for the things a good application does — handling 
chores at startup and quitting time, creating and opening docu- 
ments, handling desk accessories, and of course handling and 
sending events to the appropriate object. What does the object we 
created for this program do? Remember, that we can either add 
functionality to our object, or override existing functionality to 
change the behavior of our customized application object. 
Outside of initialization code, my application does one thing: 
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handle choices from the Graph menu, which allows the user to 
choose thecolor of the axis, plot, and background. Since we want 
to be able to set a default for the next plot, the application object 
hasthree variables which will correspond to those colors. Select- 
ing from these menus only changes the application's variable. 
When a plot is created it uses the current set of default colors. 
Once a plot is created, its colors cannot be changed. 


The Document Object 

The document object is principally responsible for only one 
thing: saving and restoring its data. While there are certainly 
other things the document must be concerned with, most of the 
document's methods will involve either saving and restoring, or 
manipulating its data structure — the document is the object 
whichisresponsible for maintaining the data that our application 
requires. In addition, each document will usually havea window 
associated with it, and it will be used to display data from the 
document. 

The standard document knows that it must be able to save 
andretrieve itself from disk, however, there's no way the generic 
document can know how you want to store your data. So, if you 
were to look in the MacApp source code, in the section that dealt 
with saving the document, you would find that the DoWrite 
method is called. However, looking at the DoWrite methods 
would not help you, since the TDocument.DoWrite method is 
empty. So what's going on here? Well, this design takes 
advantage of the inheritance chain Carl spoke of earlier. When 
you define your document class, you will implement your save 
routine for the DoWrite method that OVERRIDES (replaces) 
TDocument's DoWrite (this is where you need to understand the 
concept of OVERRIDE). When Save is selected from the File 
menu, Do Write is called for the document (your document) and 
its DoWrite method gets called — all because of the hook put in 
by MacApp. You don't have to write any code to handle disk 
errors, not enough space, etc., because MacApp does it for you 
by calling DoWrite at the right time and under the right condi- 
tions. MacApp is full of these hooks — calling a placeholder 
procedure that serves only to occupy space until you OVER- 
RIDE it to provide the needed functionality. In many cases you 
are only defining these needed override procedures. Sometimes 
itis frustrating and confusing or seems quite magical as to where 
to find these magic place holders that you can override to get the 
work done. The only advice we offer here is patience. Reading 
the documentation sometimes helps, looking at source code of 
sample programs that behave the way you want is also a good way 
to discover these placeholders and of course reading articles like 
this one. 

So what does the plotter document do? It has its own 
initialization code where it clears its copy of the quadratic 
equation parameters, and creates the window and view. Since the 
document does this work in my application, it has a method 
which will present the dialog box to the user and allow the user 
to type in parameters for the quadratic equation. Solving the 
equation is another function the document performs (note: the 
application object could have been chosen to solve the equation; 
Ichose the document object since each document carries its own 
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set of equation variables). And of course we need methods to 
write the plot out to disk. Since my plotter application does not 
read its data back in, there are no methods to read the PICT file, 
only ones to write it. 


The View Object 

The view exists to display the data in a window. Since the 
application draws quadratic equations, this is the main function 
of the view. However, there are some other functions our view 
must perform. Since good object design says data should be 
encapsulated, the view is the only object which knows its size, it 
is responsible for calculating how large it is. In the plotter 
application, the view can be one of two sizes: either the view is 
the entire size of the window or itis the size of a full page. When 
the window changes size, MacApp sends a message to the view, 
telling it to recalculate its size. Our view must know whether it 
is full page size or not, and depending on that status, must 
calculate its size. Since the view size can be changed by a menu 
choice, the view must have the necessary code to handle that 
menu choice. And of course, there must be code to enable the 
menu choices that the view can handle. 

One big difference between the MacApp and the original 
version of the plotter program is that the original plotter explicitly 
passed which device was being drawn on — the screen or the 
LaserWriter — while the MacApp program doesn't know. The 
original program did this to optimize operations for the Laser- 
Writer (as all good Macintosh programmers do): for instance, 
when drawing on the LaserWriter, the original program did not 
fill rectangles with white (since on the LaserWriter this operation 
is just a waste of time). My MacApp version did not follow this 
approach because in the MacApp structure, printing is just the 
same as drawing on the screen — the view doesn't know and 
shouldn't care which is being done. Although, I could have 
queried the global variable gPrinting to find out if the view was 
printing. MacApptakes care of all the device—specific setup, and 
our view just draws. 


The Dialog Object 

The dialog which initially appears is a simple one, but it 
serves to illustrate just how much MacApp does for us, and how 
much we don't have to worry about. Think about all the steps 
required to put up a good-looking dialog that simply requests 
some values: after theresources have been created we need to get 
the dialog (it's invisible), install a procedure for the UserItem (to 
outline the default button), stuff initial values, make the dialog 
visible, drop into a ModalDialog loop, if the default button was 
pressed then grab values from the dialog items and convert them 
back into numbers. The design of dialogs in MacApp incorpo- 
rates much of this tedious process into a complete package that 
again gets done for us. Sure, MacApp dialogs aren't free, but as 
they get more complex, MacApp's contribution becomes more 
and more significant. 


Just what is a MacApp dialog? 
While in the ‘normal’ Macintosh environment a dialog is a 
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special item, in MacApp, a dialog is simply a view (i.e., a place 
where data gets drawn) with a bunch of views within it. Every 
item in the DITL that can handle some interaction is a view, and 
these view types correspond pretty intuitively to the DITL types: 
TCheckBox, TRadioButton, TButton, TEditText, and TNum- 
berText are the major types. As you may by now assume, these 
classes respond to mouse clicks in the way we’d want them to: for 
instance, when the check box is clicked on, the TCheckBox class 
flips an internal variable and checks the control. So we don’t 
have to do anything special in this dialog to get the kind of 
interaction we want (in fact, MacApp also does the little things 
like highlighting the default button, so we have even less work to 
do). 

Our dialog box is pretty simple, since the only items in it that 
can respond to events are the six parameter EditText items. Each 
of these items is represented as a TEditText object in MacApp. 
By now you should realize that each of these ‘dialog object types’ 
has default behavior that corresponds to what we expect when we 
are in a dialog — in our case, the TEditText objects respond to 
clicks and keystrokes. Hitting a tab while in a field causes the 
succeeding field (in DITL order) tobe highlighted. This behavior 
is what we want, for the most part. 

One important sidelight is that MacApp 2.0 does not use the 
Dialog Manager for its dialogs. This has a number of implica- 
tions: dialogs are handled like other windows — in fact, you may 
have noticed that when a modal dialog comes up, the menus all 
get disabled except for the Editmenu. With MacApp, youcan use 
the Edit menu while your modal dialog is up. Another interesting 
feature is that since these modal dialogs are not real dialogs, your 
application can be switched out under MultiFinder while a modal 
dialog is on top. But back to our description... 

You may have noted that there isa TNumberText object, yet 
we used TEditText objects for numeric fields. Why? Well, 
TNumberText is only used for LongInts, and we want real 
numbers, so we will just take the strings and convert them to real 
numbersourselves (Unlike Carl, I wasn'taware of Calvin Cock's 
TExtendedTextunit that handles Reals, which he discusses later, 
so I (ugh) reinvented the wheel. Talk about an advertisement for 
being in touch.). 


What goes where? 

Oneofthedecisions you must make when writing a MacApp 
program is which objecta method belongs to. In many cases, it's 
just not clear which object should have the responsibility. Take 
cut and paste for example. On the one hand, you could consider 
that cut and paste change the data structure associated with the 
document, so they should be document-level methods. On the 
other hand, you could say that cutting and pasting change the 
appearance of the items on the screen, so they should be 
view-level methods. One way to tell that a method is in the 
wrong place is that you are constantly (i.e., more than two or three 
times) having to refer to another objects's fields to accomplish 
even a simple task. You probably have the method in the wrong 
class. Puttinga method in the wrong class makes the method look 
messier or more complicated than it is. You will usually find 
yourself doing something like: 
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a:= TMyDoc.fMyView.fMyViewData.fGetaV alue; 


Another way to tell if a method is “misassigned” is to see if 
you rely on information that isn’t plainly available to your object 
toenable or disable the menu item associated with thatcommand. 
If, for instance, you have cut and paste associated with the 
document, and you need to ask the view if any items are 
highlighted so you can tell if you should enable the menu items, 
then you either have a bad design or you have the method in the 
wrong class. 


Discussion of the program 

At this point, I'd like to move through the source files and 
point out where you will find the pieces I have described. The 
source files consist of three types of files: Pascal (MacApp) 
Source, resources, and the makefile. The source files will merit 
most of the discussion, so let's start with them. 

Main program file (MOPlot.p) 

All MacApp main programs look pretty much alike. After 
the necessary junk at the beginning at the file, the main program 
starts. Main programs are boring, because so much of the 
Macintosh functionality is rolled up into the application object. 
A MacApp main program does the following: initialize the 
Toolbox Managers and other needed functions, create the appli- 
cation object, call its initializing method, then call its Run 
method. That's it, and that's usually always it; when Run returns 
the program execution ends. 

| 1 n P 

MacApp source files have a strange arrangement forced 
upon them by MacApp. The .inc1 source file is organized by 
object hierarchy: first the application, then the document, and last 
the view (remember, the dialog view does not have a customized 
object because the standard dialog handling was sufficient for 
Our purposes). 

As we mentioned before, the application object is a simple 
one, since there is nottoo much to do. In order to handle the menu 
choices relating to the color selections, we need to override 
DoSetupMenus and DoMenuCommand, and both of those meth- 
ods are pretty easy to understand. Remember, the DoSetup- 
Menus method is called by MacApp frequently (you won't 
believe just how frequently) so there shouldn't be any lengthy 
calculations here. If you need to do some complicated calcula- 
tions to determine if some menu item should be enabled, you 
should do it somewhere else (like in the idle chain) and set a flag 
or value in your object; that flag can then be used for the menu 
enabling. The only other method of interest is a real short one: 
HandleFinderRequest. MacApp's default behavior for applica- 
tions is that when an application is launched from the Finder by 
doubleclicking on the application icon, a blank document opens. 
Well, we don't want that to happen, since our document is the 
plot, and we wouldn't want a blank plot window on the screen. 
So, to modify this behavior, we just override HandleFinderRe- 
questand do nothing. Now when the application is launched, our 
HandleFinderRequestis called instead of the default one, and we 
don't get a empty document. This method is a demonstration of 


437 


the small things you sometimes have to do to make your applica- 
tion ‘perfect’ — and note that it’s not difficult, it just requires 
knowing what's going on and where to look. [Carl's Note: In 
many ways this typifies the MacApp design - the methods are 
there to do the kind of things you will need to do - you just have 
to look for them.] 

The document methods can be characterized into three 
categories: initialization, solving the quadratic equation, and 
saving the PICT data. Initialization methods are not very 
interesting, except to note that the DoMakeViews and DoMa- 
keWindows methods are some more of the methods which you 
are required to OVERRIDE orelse your program will not work 
(Actually that’s not really the truth — with MacApp 2.0 you can 
omit these overrides and your program will work, it’s just that 
you’ll get the default view and window size/location). The 
method titles are fairly self explanatory. Solving the quadratic 
equation involves a few methods which contain a lot of code 
lifted directly from the original plotter application. All I did for 
these methods was put the method syntax before and after them, 
and change the variable references to refer to the document 
object’s variables instead of some global variables. The last few 
methods deal with saving the data to disk. As mentioned before, 
there are really two methods necessary to save data on disk: 
DoNeedDiskSpace — which calculates if the file will fit on the 
disk, and DoWrite — which actually writes out the data. If there 
seems to be a lot missing from the implementation of the disk 
handling, remember that MacApp does most of the work for us 
— opening the file and checking for errors. Again, all we have 
to dois handle our application’s specific needs, which in this case 
is saving the PICT. 

The view object contains some initialization methods 
(which should be quite familiar by now). After that is a method 
called CalcMinSize. This method is called (by MacApp of 
course) when the size of the view needs to be determined. 
Remember, the view can be either the size of the window or the 
size of an entire page. So we need to have a flag (fOnePage) 
which tells us which is the case. If we are an entire page, we tell 
MacApp that our size is the size of our print handler’s page (since 
we want the printout to be one page). If we are not the size of a 
page, we tell MacApp our size is the size of our superview (our 
superview is the view which we are inside. In the case ofa simple 
view, our superview is the window itself). After the menu 
handling routines (DoSetupMenus and DoMenuCommand) we 
have a large method which prints the plot on the LaserWriter 
(again, this method was stolen directly from the original plotter 
application and had some method syntax wrapped around it). 
The next two methods were written to handle the case where the 
window is resized. In Super ViewChangedSize, we check to see 
if we are displaying the plot in full page mode. If not, when the 
window changes size we need to change the size of the view 
(since the view mirrors the window size). The next method, 
Resize, has been overridden because when the view size changes 
we want to force the view to be redrawn (i.e., when switching 
between full page and window size display modes). The last 
view method just draws the view, and it is also pretty simple. 

R file (QPlot.r 
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Resources for a MacApp program are almost identical to 
those for a non-MacApp program. There are only two differ- 
ences (and they are big differences): ‘cmnu’ instead of ‘MENU’ 
and ‘view’ resources. ‘cmnu’ resources (probably stands for 
‘Command Menu") are used to associate menu items with com- 
mand numbers. Carl and I have both spoken of the usefulness of 
command numbers, and I don't need to reiterate it here. The view 
resource is different, and is a crucial resource in your MacApp 
program. Carl will speak about view resources in greater detail, 
but let me say that the view resource allows you to specify the 
contents of your windows (in functional areas). You can (and 
will) use viewsto specify your dialogs in MacApp, because these 
dialogs are build out of views, as we mentioned earlier. The 
benefit of using a view resource is the same as you get anywhere 
else in using resources: you can change the resource without 
having to recompile the source code. While it may seem that this 
benefit is limited with regard to views, I’m sure you can attest to 
the value of resources in other areas, and isn't it nice to be able 
to ‘tweak’ a resource quickly? 

One other thing you should know about MacA pp resource 
files is that MacApp has a default number for the about box. If 
you can live with a boring about box (i.e., an ALRT) then you 
should create it with id 201. That's because as part of the generic 
Macintosh application that MacApp implements, when you 
select the About Application... from the Apple menu, you get 
ALRT 201 displayed. If you like that, it's great, and as always, 
if you don't like it, you can easily override it. In fact, I override 
it in my program because I want to calculate some system 
parameters. I'm sure that you realize the proper method is in the 
Application level object (since of course the application handles 
requests to display the about box). 

file (OPlot.MAmak 

The makefile is something many Lightspeed users are unfa- 
miliar with. MacApp2.0's MABuildprocess eliminates the need 
for a makefile in simple cases. I have provided a simple make 
file, it's not much, as you can see from the listing. When your 
program becomes more complicated the makefile usually grows 
proportionally in complexity. For small projects made up of two 
or three files, the example makefiles in the MacApp samples 
folder can be used as guides (and of course, you can consult the 
manual for more explanation). 


Trouble In Paradise 

One last parenthetical note before we move over to Carl's 
description of his program. When we both did the conversions, 
we independently had problems printing the plots on the Laser- 
Writer — PostScript errors. I tore my hair out about it for a few 
weeks, then decided to really dig down and see what was 
happening. By strategically inserting debugging statements into 
my code I finally isolated my bug to a PicComment call. The 
PicComment in question sets the linewidth, and looks like this: 


PicComment(SetLineWidth, 2,HandleCwWidth)); 


However, the real call should look like this: 
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PicComment(SetLineWidth,4,Handle(Width)); 


The problem was that the second parameter to the PicCom- 
mentissupposed to be the size (in bytes) of the data. The original 
specification was wrong, yet it worked (we assume) because 
Lightspeed Pascal must be more forgiving than MPW. Not only 
was this line a bug, but the Daves even featured the bug in their 
article (top of page 21)!! Let this be a lesson that just because 
someone gives you code that works you can’t assume that it is 
completely bug-free. 

That just about covers my program; Next month, we'll hear 
about Carl's. 


( ) 

File MQPlot.p > 
($P) 

(MQPlot.p) 


(Copyright € 1989 by Charles F. McMath A11 rights reserved.) 


( This is the main program for the MacApp 

plotter application. The original plotter was 
written by Dave Smith and Dave Kelly for MacTutor 
Magazine. This coversion was done by Chuck 
McMath to demonstrate the same program done using 
MacApp. It also hopefully demonstrates some of 
the strengths of MacApp! 

) 


PROGRAM QPlot; 


USES 

( 0 MacApp ) 

UMacApp, 

( 0 Building Blocks ) 

UDialog, UPrinting, 

( 0 Implementation Use ) 

SANE, ToolUtils, Fonts, Resources, Script, 
PickerIntf, Packages, 

(0 the PlotUNIT ) 

UQP lot; 


VAR 
güPlotApplication:  TQPlotApplication; 
BEGIN 
Ini tUMacApp(5); 
InitUDialog; 
InitPrinting; 


New(gQPlotAppl ication); 

gQPlotApplication. 
IQPlotApplicationCkF i leType?; 

gQPlotApplication.Run; 


END 
(— D, 
E File UQPlot.p ————) 


(Copyright € 1989 by Charles F. McMath. 
A11 rights reserved.) 


UNIT UQPlot; 
INTERFACE 


USES 
( O MacApp - this includes all of the 
things necessary from the MacApp Library ) 
UMacApp, 
( 0 Building Blocks } 
UDialog, UPrinting, 
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( 9 Implementation Use ) 
SANE, ToolUtils, Fonts, Resources, Script, 
PickerIntf, Packages; 


CONST 
kSignature = ‘FGT3’; (Appl. signature) 
kF i leType = ‘PICT’; (our filetype ) 
kQPlotWindowID = 1001; 

TYPE 


TQPlotApplication = ОВЈЕСТСТАрр1 ication) 
fDefGraph: INTEGER; { Graph color index ) 
fDefAxis: INTEGER; ( Axis color index ) 
fDefBack: INTEGER; ( Back color index ) 
fPrintOpt: INTEGER; ( Page/Window size ) 


PROCEDURE TQPlotApplication. 
IQPlotApplication 
CitsMainF i leType:O0SType); 
FUNCTION  TQPlotApplication.DoMakeDocument 
CitsCmdNumber : CndNumber ): TDocument; 
OVERRIDE; 
PROCEDURE TQPlotApplication. 
HandleF inderRequest; OVERRIDE; 
PROCEDURE TQPlotApplication.DoSetupMenus; 
OVERRIDE: 
FUNCTION TQPlotApplication.DoMenuCommand 
CaCndNumber: CmdNumber): TCommand; 
OVERRIDE; 
PROCEDURE TQPlotApp] ication. ShowAboutApp; 


2 


TQPlotDocument = OBJECT(TDocument) 
fAParam: Real; ( these parameters ) 
fBParam: Real; ( correspond ) 


to those } 
fCParam: Real; ( in the quadratic ) 
fStep: Real; ( equation. ) 
fXScale: INTEGER; ( X exis scale ) 
fYScale: INTEGER; ( Y axis scale ) 
fResult: INTEGER; ( real results? ) 


fRoot 1: REAL; 
fRoot2: REAL; 


( first root ) 
( second root ) 


fPlotView: TQPlotView; 


PROCEDURE TQPlotDocument . IQPlotDocument 
CitsFileType, itsCreator: OSType; 
usesDataFork, usesRsrcFork: BOOLEAN; 
keepsData0pen, keepsRsrcOpen: 
BOOLEAN); 

PROCEDURE TQPlotDocument .DoMakeW indows; 

OVERRIDE; 

PROCEDURE TQP lotDocument . DoMakeV iews 

(forPrinting: BOOLEAN); OVERRIDE; 


PROCEDURE TOP lotDocument .PoseP lotD ialog; 
PROCEDURE TQPlotDocument . Quad 
(а, b, с: REAL;VAR хі, x2 : REAL; 
VAR result : INTEGER); 
FUNCTION TQPlotDocument .Solvelt 
(a, b, c: REAL; VAR x1, x2: REAL): 
INTEGER; 


PROCEDURE TQPlotDocument .DoNeedD iskSpace 

(VAR. dateForkBytes, 

rsrcForkBytes: LONGINT); OVERRIDE; 
PROCEDURE TQPlotDocument .DoWrite 

CaRefNum: INTEGER; 

mak ingCopy: BOOLEAN); OVERRIDE; 
END ; 


TQPlotView = OBJECTCTView) 
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fPlotDoc: TQPlotDocument; ( link to doc ) 
fOnePage: BOOLEAN; ( if TRUE, page size ) 
fDrawing: PicHandle; ( our picture! ) 


PROCEDURE TQPlotView.IQPlotView 
CtheDoc: TQPlotDocument; 
theGrafColor, theAxisColor, 
theBackColor: INTEGER); 
PROCEDURE TQPlotView.Free; OVERRIDE; 


PROCEDURE TQPlotView.CalcMinSize 
(VAR. minSize: VPoint); OVERRIDE; 
PROCEDURE TQP 1otV iew.DoSetupMenus; 
OVERRIDE; 
FUNCTION TQPlotView.DoMenuCommand 
CaCmdNumber: CmdNumber): TCommand; 
OVERRIDE ; 


PROCEDURE TOPlotView.PrQDStuff 

(pRect : rect; QDdevice : integer), 
PROCEDURE TQP1lotV iew.SuperViewChangedSize 

(delta: VPoint; 

invalidate: BOOLEAN); OVERRIDE; 
PROCEDURE TQPlotView.Resize 

(width, height: VCoordinate; 

invalidate: BOOLEAN); OVERRIDE; 
PROCEDURE TQPlotView.DrawCarea: Rect); OVERRIDE; 
END ; 


IMPLEMENTATION 
($1 UQPlot. inc1.p)} 


END . 


) 


(Copyright @ 1989 by Charles F. McMath. 
All rights reserved.) 


(—________—_} 
(——- File UQPlot.inci.p 


CONST 
kPlotWindowID = 1001; 
kPlotDLOG - 2000; 
kPlotID = 'PPRM'; 


kStaggerAmt= 16; 


( these are command numbers ) 


cGraphColor = 1201; 
cAxisColor = 1202; 
cBackColor = 1203; 
cGraf Black = 10001; 
cGrafWhite = 10002; 
cGrafRed = 10003; 
cGrafGreen = 10004; 
cGrafBlue = 10005; 
cGraf Cyan = 10006; 
cGraf Magenta = 10007; 
cGrafYellow = 10008; 
cAxisBlack = 11001; 
cAxisWhite = 11002; 
cAxisRed = 11003; 
cAxisGreen = 11004; 
cAxisBlue = 11005; 
cAxisCyan = 11006; 
cAxisMagenta = 11007; 
cAxisYellow = 11008; 
сВаскВ1аск = 12001; 
cBackWhite = 12002; 
cBackRed = 12003; 
cBackGreen = 12004; 
cBackBlue = 12005; 
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cBackCyan = 12006; 

cBackMagenta = 12007; 

cBackYel low = 12008; 

cPrintwS = 1301; 

cPrintPS = 1302; 
(Ж 


х The following constants relate to 0106 
*and ALRT numbers. 


x) 
kAboutDLOG = 1024; ( our about box ) 
VAR 
gStaggerCount: INTEGER; 
colors: ARRAY (1..8] OF INTEGER; 
crString: Str255; 


FUNCTION Int2Str(thelnt: INTEGER): Str255; 
(x 


*This utility function takes an integer and 
* converts it into a string. 
х) 
VAR 
tempLong: LongInt; 
tempStr: 517255; 
BEGIN 
tempLong := theInt; 
NumToString(tempLong, tempStr); 
Int2Str := tempStr; 
END; ( Int2Str ) 


=n 
FUNCTION Real2String(theReal: REAL; 
numDigits: INTEGER): Str255; 
*This function takes a real number, 

* and converts it to a string with 

* the specified number of digits PAST the 
* decimal point. 


х) 
VAR 
theForm: DecForm; 
xTemp: Extended; 
tempStr: DecStr; 
BEGIN 


theForm.style := FixedDecimal, 
theForm.digits := numDigits; 


xTemp :- theReal; 
Num2StrCtheForm, xTemp, tempStr); 
Real2String := tempStr; 

END; (Real2String ) 


FUNCTION String2Real(theString: Str255): REAL; 
(* 
*This function takes a string form of a real 
* number, and converts it into the real number. 
x) 
VAR 
xTemp: Extended; 
BEGIN 
xTemp := Str2Num(theString); 
String2Real := Num2Real(xTemp); 
лы ( String2Real ) 


(— QPlot Application кшн — 


( 
PROCEDURE TQPlotApplication.IQPlotApplication 
CitsMainFileType: 05Туре); 
(* 
*This procedure initializes the application. 
* It sets up all of our global variables and 
* fills the color index array. 
x) 
VAR 
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aQPlotView:  TQPlotView; 
BEGIN 
IApplication(itsMainFileTupe); 


crString[0] := CHR(1); 
crString[1] := CHR(13); 


colors[1] := 33; ( black ) 
colors[2] := 30; ( white ) 
colors[3] := 205; ( red ) 
со10г8141 := 341; ( green ) 
colors[5] := 409; ( blue ) 
colors[6] := 273; ( cyan } 
colors(7] := 137; ( magenta ) 
colors[8] := 69; ( yellow ) 
fDefGraph := colors[3]; 


fDefAxis := colors[1]; 
fDefBack := colors[21: 
fPrintOpt := 1; 


gStaggerCount := Ø; 
run m TüPlotApp! ication. шыш ) 


FUNCTION TQPlotApplication.DoMakeDocument 
CitsCmdNumber: CmdNumber): TDocument; 
OVERRIDE; 
(x 
*This function is called whenever we're 
* creating a new document. It creates the 
* document object and returns it (properly 
* initialized, of course). 


ж) 
VAR 
aQPlotDocument: TQPlotDocument; 
BEGIN 
NewCaQPlotDocument); 


FailNilCaQPlotDocument); 
eQPlotDocument . IQPlotDocument 
СКР іТеТуре, kSignature, 
kUsesDataFork, NOT kUsesRsrcFork, 
NOT kDataOpen, NOT kRsrcOpen); 


aQPlotDocument.fSavePrintInfo := FALSE; 
DoMakeDocument := aQPlotDocument; 
END ; ( TOP lotApp1 ication. DoMakeDocument ) 


PROCEDURE TQPlotApplication.HandleFinderRequest; 
OVERRIDE; 
BEGIN 


( just override this so we don’t put up a 
blank document } 
END ; ( ао еве ) 


PROCEDURE TQPlotApplication.DoSetupMenus; 
OVERRIDE; 
(* 
*This procedure enables the appropriate menu 
* items for the application. 
х) 
BEGIN 
INHERITED DoSetupMenus; 


Enable(cGraphColor, TRUE); 
EnableCcAxisColor, TRUE); 
EnebleCcBackColor, TRUE); 

(* 

*Enable all of these, and put a check bU 

* the current one. 

x) 


EnableCheckCcGrafBlack, TRUE, 
fDefGraph-colors[11); 

EnableCheck(cGrafWhite, TRUE, 
fDefGraph=colors[2]); 
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EnableCheck(cGrafRed, TRUE, 
fDefGrephzcolors[31); 
EnableCheck(cGrafGreen, TRUE, 
fDefGraph= colors[4]); 
EnableCheck(cGrafBlue, TRUE, 
fDefGraph= colors[5]); 
EnableCheck(cGrafCuan, TRUE, 
fDefGraph=colors[6]); 
EnableCheck(cGrafMagenta, TRUE, 
fDefGraph=colors{7]); 
EnableCheck(cGraf Yellow, TRUE, 
fDefGraph=colors[8]): 


EnableCheck(cAxisBlack, TRUE, 
fDefAxis= colors[ 11); 
EnableCheck(cAxisWhite, TRUE, 
fDef Axis= colors[21); 
EnableCheck(cAxisRed, TRUE, 
fDef Axis= colors[3]); 
EnableCheck(cAxisGreen, TRUE, 
fDefAxis= colors[4]); 
EnableCheck(cAxisBlue, TRUE, 
fDefAxis= colors[51); 
EnableCheckCcAxisCyan, TRUE, 
fDefAxis=colors[6)); 
EnableCheck(cAxisMagenta, TRUE, 
fDefAxis=colors(7]); 
EnableCheckCcAxisYellow, TRUE, 
fDefAxiss colors[81); 


EnableCheck(cBackBlack, TRUE, 
fDefBackscolors(11); 
EnableCheck(cBackWhi te, TRUE, 
fDefBackzcolors[21); 
EnableCheck(cBackRed, TRUE, 
fDefBack=colors(31). 
EnableCheck(cBackGreen, TRUE, 
fDefBackscolors[41); 
EnableCheck(CcBackBlue, TRUE, 
fDefBackzcolors(512; 
EnableCheckCcBackCyan, TRUE, 
f Def Back=colors[6]); 
EnableCheck(cBackMagenta, TRUE, 
fDefBack=colors[7]); 
EnableCheck(cBackYellow, TRUE, 
f Def Back= colors[8]); 


0; ( li еш ) 


FUNCTION TQPlotApplication.DoMenuCommand 
CaCmdNumber: CmdNumber): TCommand; 
OVERRIDE; 
(* 
*This function handles menu requests that 
* pertain to the application. It ensures that 
* choices that change colors work correctly. 
ж) 
ВЕСІН 
DoMenuCommand := gNoChanges; 
CASE aCndNumber OF 
cAboutApp: ShowAboutApp; 
cGrafBlack, 
cGrafWhite, 
cGrafRed, 
cGrafGreen, 
cGrafBlue, 
CGrafCyan, 
cGraf Magenta, 
cGrafYellow: 
fDefGraph := colorslaCmdNumber - 
cGrafBlack + 1]; 
cAxisBlack, 
cAxisWhite, 
cAx isRed, 
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cAxisGreen, 
cAxisBlue, 
cAxisCyan, 
cAxisMagenta, 
cAxisYel low: 
fDefAxis := colors[aCmdNumber - 
cAxisBlack + 1); 
cBackB lack, 
cBackWhite, 
cBackRed, 
cBackGreen, 
cBackBlue, 
cBackCyan, 
cBackMagenta, 
cBackYellow: 
fDefBack := colors[aCmdNumber - 
cBackBlack + 1], 


cPrintws, 
cPr intPS: 
fPrintOpt := aCmdNumber - 
cPrintwS + 1; 
OTHERWISE 


DoMenuCommand := INHERITED 
DoMenuCommand(aCmdNumber 2; 
END; (cese) 
END; (TQPlotApplication.DoMenuCommand ) 


PROCEDURE DrawBoxCwPtr: WindowPtr; itemNum: INTEGER); 
(* | 

XThis procedure is the UserItem proc that 

x gets called for the about box. 


x) 
VAR 
itup: INTEGER; 
itemHdl: Handle, 
tRect: Rect; 
BEGIN 


GetDI tem(DialogPtrCwPtr), 5, ityp, itemHdl, tRect); 
FrameRect(tRect); 
END; ( DrawBox ) 


( ) 

PROCEDURE TQPlotApplication.ShowAboutApp; 

(* 

*Show our about box. This version is almost 

х identical to the original, except for the 

х addition of some stuff about MacApp 

* (incidentally, this is required by the license 
х agreement for programs developed with MacApp! ) 
ж) 


VAR 
idStrHandle: StringHandle; 
freeSpace: Size; 
myHeapSpace: ^ LongInt; 
tempStr 1: Str255; 
tempStr2: Str255; 
tempStr3: 947255; 
diaPtr: DialogPtr; 
itemHit: INTEGER; 
ityp: INTEGER; 
itemHd1: Handle; 
tRect: Rect; 

BEGIN 
idStrHandle :- 


StringHendleCGetResource(kSignature, 22); 
FailNILCidStrHandle); 


MoveHHiCHandleCidStrHendle2); 
HLockCHandleC idStrHandle)2; 


freeSpace := FreeMen; 

myHeapSpace := MaxMem(freeSpace); 
NumToString(myHeapSpace, tempStr2); 
tempStr2 := concat( ‘Memory = ', tempStr2); 


442 


[4 ГА . 


tempStr3 : 
tempStr 1 : 
ParamText(idStrHandle^^, tempStr1, tempStr2, tempStr3); 
diaPtr := GetNewDialog(kAboutDLOG, NIL, Pointer(-1)); 
FailNIL(diaPtr); 

GetDItem(diaPtr, 5, ityp, itemHdl, tRect); 
SetDItem(diaPtr, 5, itup, Handle(@DrawBox), tRect); 


4 
2. 


InitCursor; 
ModalDialog(NIL, itemHit); 
DisposDialog(diaPtr); 


HUnlock(Handle(idStrHandle)); 
END; (TQPlotApplication.ShowAboutApp ) 
D ы ыы ы а) 


( 
(—— QPlot Document Methods ----) 


[(——  ə 
PROCEDURE TQPlotDocument.IQPlotDocument 
CitsFileType, itsCreator: OSTupe; 
usesDataFork, usesRsrcFork: BOOLEAN; 
keepsDataOpen, keepsRsrcOpen: 
BOOLEAN); 
(* 
*Initialize the QPlot document. For our 
x document, this means that we will present the 
* dialog box that asks for the quadratic 
х parameters, and we'l! solve the equation while 
* we’re here. 
x) 


x1, x2: REAL; 


IDocument(itsFileTupe, itsCreator, usesDataFork, us- 
esRsrcFork, keepsDataOpen, keepsRsrcOpen); 


PosePlotDialog; 
fResult := SolveIt(fAParam, fBParam, 
fCParam, x1, x2); 
IF (fResultOo-1) THEN 
BEGIN 
fRoot! : 
fRoot2 : 


х1, 
х2, 


fRoot1 := -999; 
= -999 


fPlotView := NIL; 
END; ( TQPlotDocument.IQPlotDocument ) 


(—— ə Ls 
PROCEDURE TQPlotDocument.DoMakeWindows; OVERRIDE; 
(ж 
*This procedure is called when we have to 
* make a new document (and its associated 
х window). We just get a simple window and shove 
* it on the screen. 
x) 
VAR 
aWindow: TWindow; 
BEGIN 
aWindow := NewSimpleWindow(kPlotWindowID, 
kWantHScrollBar, kwantVScrollBar, SELF, fPlotView); 
aWindow.SimpleStagger(kStaggerAmt, 
kStaggerAmt, gStaggerCount); 
END; (TQPlotDocument.DoMakeWindows ) 


) 
PROCEDURE TQPlotDocument .DoMekeV iews 
(forPrinting: BOOLEAN); OVERRIDE; 

(* 

*This procedure is called when we are making 

* а new document. It creates all views that are 

X needed. In our case, it’s only one. We then 

* initialize the view. 
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е) 


VAR 
plotApp: TQPlotApplication; 
eQPlotView:  TQPlotView; 
aHandler: TStdPr intHandler; 
tRect : Rect; 
BEGIN 
plotApp := TQPlotApplicationCgApplication); 
NEWCaQPlotView); 
FailNILCaQPlotView); 


aQPlotView.IQPlotViewCSELF, 
plotApp.fDefGraph, plotApp.fDefAxis, 
plotApp. fDefBack); 


fPlotView := aQPlotView; 
(* 
*Now make the view printable by creating a 
x print handler. 
х) 
IF NOTCforPrinting) THEN 
BEGIN 
New(CaHandler ); 
FailNILCaHandler?; 
eHandler . IStdPr intHandler(SELF, 
eQPlotView, FALSE, TRUE, TRUE); 
( set up for 1/2" margins ) 
SetRect(tRect, 35,35, -35, -35); 
eHandler.InstallMarginsCtRect, FALSE); 
END ; 
vied ( СООР ) 


PROCEDURE TQPlotDocument.PosePlotDialog; 
(* 
*This procedure puts up the dialog that 


* requests the quadratic parameters. 
х) 


FUNCTION CvtEditRealCaText: TEditText): 
Real; 
VAR 
tempStr: 817255; 
BEGIN 
alext.GetText(tempStr); 
CvtEditReal := String2Real(tempStr); 
END; ( CvtEditReal ) 


FUNCTION CvtEditIntCaText: TEditText): 


INTEGER; 
VAR 
tempStr: Str255; 
tempLong: LongInt; 
BEGIN 


alext.GetText(tempStr); 
StringToNumCtempStr, tempLong); 
CvtEditInt := tempLong; 
END; (CvtEditInt ) 
AR 


aWindow: TWindow; 
dismisser:  IDType; 


aQPlotView: TQPlotView; 


dView: TDialogView; 
enEditText: TEditText; 
aVal: TEditText; 
bVal: TEditText; 
cVal: TEditText; 
stepVal: TEditText; 
xVal: TEditText; 
yVal: TEditText; 
tempStr: 517255; 

BEGIN 

(* 
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*First make our calls (which never get 

* executed) to tell the linker we want to create 
* these types of objects. 

х) 


IF gCreateWithTemplates ТНЕМ 
BEGIN 
NEW(aQPlotView); 
NEW(dView); 
NEW(anEditText); 
END ; 

(* 


*Get the dialog window and find the dialog subview. 


ж) 
aWindow := NewTemplateWindowCkPlotDLOG, NIL); 
dView := TDialogView(aWindow. 
FindSubView(kPlotID)); 
(* 
*Retrieve references to each of the edit 
x text items. We will need to reference them 
x later to get their values. 


= TEditText(dView.FindSubView(’a 4); 
bVal := TEditText(dView.FindSubView(’b — '2); 

= TEditText(dView.FindSubView(’c — '2); 
StepVal := TEditText(dView.F indSubView( ‘step’ )); 
xVal := TEditText(dView.F indSubView( ’xscl’)): 
yVal := TEditText(dView.F indSubView( ‘ysc]’)); 


dView.SelectEditText('a  ', kRedraw); 


dismisser :- dView.PoseModally; 
(x 
*Now that we have the values, convert them 
* to numbers and plug them into the quadratic 
* equation solver. Note that we don't test to 
* see if the OK button was pressed, because in 
х this dialog, you can't exit except by saying 
* OK. 


х) 
fAParam :- CvtEditReal(aVal); 
fBPeram := CvtEditReal(bVal); 
ТСРагат := CvtEditReal(cVal); 
fStep := CvtEditReal(stepVal); 
fXScale := CvtEditInt(xVal); 
fYScale := CvtEditInt(yVal); 


aWindow.Close; 
END; (TQPlotDocument .PosePlotDialog ) 


PROCEDURE TQPlotDocument.Quad(a, b, c : REAL; 
VAR x1, x2 : REAL; 
VAR result : INTEGER); 
(x 
*This procedure is identical to the one 
x written in ‘vanilla’ Pascal 
x) 
VAR check : real; 


FUNCTION PositiveCalc 
(a, b, check : real) : real; 


BEGIN 
PositiveCalc := (-b + sart(check)) / 
(2 * a); 
END; (PositiveCalc -—— ) 


FUNCTION NegativeCalc 
(a, b, check : real) : real; 


BEGIN 
NegativeCalc := (-b - sart(check)) / 
(2 х a); 
END; ( NegativeCalc -—— ) 
BEGIN 
result := 0; 


443 


check := (b * b) - (4 ха ¥ c); BEGIN 


IF result = 0 THEN INHERITED DoWrite(aRefNum, makingCopu); 
BEGIN (* 
( Check if double root exists ) *Now write the blank 512 byte header needed 
IF check = 0 THEN * for PICT files. 
BEGIN X) 
result := 2; FOR i:= 1 TO 256 DO 
х1 := positivecalc(a, b, check); buffer[il := Ø; 
x2 := x1; | 
END ; count := 512; 

( Check if real result) err := FSWrite(aRefNum, count, @buffer); 
IF check › 0 THEN IF ((errOonoErr) OR Ccount 05122) THEN 
BEGIN SysBeep( 10); ( 888 error alert ) 

result := 1; 
х1 := positivecalc(a, b, check); pHdl := fPlotView. fDrawing; 
x2 := negativecalc(a, b, check); HLockCHandle(CpHd122; 
END ; count := GetHandleSizeCHandleCpHd12)); 
( Check if root is complex ) err := FSWriteCaRefNum, count, Ptr(pHd1*)); 
IF check « 0 THEN HUnlock(Hand1e(pHd1)); 

BEGIN IF (Cerr ОпоЕгг) OR 
result := 3; (count o GetHandleSizeCHandleCpHd1222) THEN 
check := -check; SysBeep(10); ( 006 error alert ) 
х1 := positivecalc(a, b, check); END; (TQPlotDocument.DoWrite ) 
x2 := negativecalc(a, b, check); (——————————) 
END ; (——- QPlot View Methods —— —) 

END ; | 0с---------” 

END; ( TQPlotDocument.Quad } PROCEDURE TQPlotView.IQPlotView(theDoc: 
—PN TQPlotDocument; theGrafColor, 

FUNCTION TQPlotDocument.SolveItCa, b, c: REAL; theAxisColor, theBackColor: INTEGER); 

VAR x1, x2: REAL): INTEGER; (* 

(* *This procedure is called to initialize a 
XThis function is identical to the one * QPlot view. It sets the view’s variables to 
X written for the original program. * good initial values. 

x) x) 
VAR VAR 
result: INTEGER; vOrigin: МРоіп+; 

BEGIN vSize: VPoint; 

IF Ca o 0) THEN tempPort: GrafPtr; 
quad(a, b, c, хі, x2, result) BEGIN 

ELSE SetVPt(vOrigin, 0, 0); 
result := -1; SetVPt(vSize, 600, 400); 

SolveIt := result; 

END; ( eens ) IView(theDoc, NIL, vOrigin, vSize, sizeVariable, sizeVari- 
— able); 

PROCEDURE TQP lotDocument .DoNeedD iskSpace fPlotDoc := theDoc; 

(VAR dataForkBytes, 
rsrcForkBytes: LONGINT); OVERRIDE; fDrawing := NIL; 
(* fOnePage := FALSE; 
*This procedure calculates the amount of END; (TQPlotView.IQPlotView ) 
ж disk space we need to store our document on (— 
* disk. In our case, it’s just the size of the PROCEDURE TQPlotView.Free; OVERRIDE; 
* drawing since no additional information is (* 
* stored in our file. *This procedure is called when the view is 
*) * finished, and we are cleaning up anu space we 
BEGIN * have allocated. We just dispose of the picture 
INHERITED DoNeedD iskSpace(dataForkBytes, rsrcForkBytes); * handle. 
х) 
dataForkButes := dataForkBytes + BEGIN 
512 ( header ) + KillPicture(fDrawing); 
GetHandleSize(Handle(fPlotView.fDrawing)); INHERITED Free; 
END; ( Hen EO Ps: ) но, ( TQPlotView.Free ) 
PROCEDURE TQPlotDocument .DoWriteCaRefNum: INTEGER; PROCEDURE TQPlotView.CalcMinSize 
mak ingCopy: BOOLEAN); OVERRIDE; (VAR minSize: VPoint); OVERRIDE; 
(* (* 
*This procedure is called to write the data *This procedure is called to calculate the 
* onto the disk. * minimum size of the view. It is called 
х) х initially when the view is being created, and 
VAR x later on when we tell the view to recalculate 
count: Longlnt; * its view size. 
buffer: ARRAY [1..256] OF INTEGER; x) 
pHd1: PicHandle; VAR 
і: INTEGER; vSize: Point; 
err: 05Егг; tWind: Twindow; 
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tRect: Rect; 
BEGIN 
INHERITED CalcMinSize(minSize); 
IF fOnePage THEN 
BEGIN 
minSize := fPrintHandler f ViewPerPage; 
END 
ELSE 
BEGIN 
IF C(fSuperView ONIL) THEN 
minSize := fSuperView.fSize 
ELSE 
BEGIN 
vSize := Point(0); 
IF SELF.Focus THEN ; 
QDToV iewPtCvS ize, minSize); 
END ; 
BO ( ср ) 


PROCEDURE TQPlotView.DoSetupMenus; OVERRIDE; 
(* 


*This procedure is called to enable menu 
x items that pertain to the view. 
ж) 
BEGIN 
INHERITED DoSetupMenus; 


EnableCheck(cPrintWS, TRUE, NOT fOnePage); 
EnableCheck(cPrintPS, TRUE, fOnePage); 
END; ( ОСЕ NE ) 


FUNCTION TQPlotView.DoMenuCommand 
CaCmdNumber: CmdNumber): TCommand; 
OVERRIDE; 
(x 
*This function is called to handle menu 
* commands that pertain to the view. 
x) 
VAR 
tempVPt: VPoint; 
tRect: Rect; 
BEGIN 
DoMenuCommand := gNoChanges; 
IF CaCmdNumber = cPrintWS) OR 
CaCmdNumber = cPrintPS) THEN 
BEGIN 
fOnePage :- CaCmdNumber=cPr intPS); 
AdjustSize; 
END 


ELSE 
DoMenuCommand := 
INHERITED DoMenuCommand(aCmdNumber ); 
Во; ( IQPlotView.DoMenuCommand ) 


------------) 
PROCEDURE TQPlotView.PrQDStuff(pRect : rect; 
QDdevice : integer); 
(* 
*This is the main drawing procedure for the 
* view. It is (almost) unchanged from the 
* original version. Since in MacApp you don’t 
* know who you’re drawing for (Display vs. 
* LaserWriter) most of the display-specific code 
* has been deleted. Drawing still works 
* correctly, since we erase the invalid 
* areas before we draw it. 
x) 
CONST 
Display = 1; 
LaserWriter = 2; 
ImageWriter = 3; 


NoJust 


= 0; 
LeftJust = 


1; 
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CenterJust = 2; 
RightJust = 3; 
FullJust = 4; 
LinesInParagraph = 5; 
(selected MacDraw comments) 
picDwgBeg = 130; 
picDwgEnd = 131; 
picGrpBeg = 140: 
picGrpEnd = 141; 
TextBegin = 150; 
TextEnd = 151; 
StringBegin = 151; 
StringEnd = 153; 
TextCenter = 154; 
(postscript comments) 
SetLineWidth = 182; 
PostScriptBegin = 190; 
TextIsPostscript = 194; 
PostScriptEnd = 191; 
TYPE 
widhdl = ^widptr; 
widptr = ^widpt; 
widpt = Point; 


TTxtP icRec = PACKED RECORD 
tJus : Byte; 
tFlip : Byte; 
tRot : Integer; 
tLine : Byte; 
tCmnt : Byte; 


4 


VAR 
le, tp, ri, bo : integer; 
strl, str2, str3, str4, str5 : str255; 
str6, str7, str8, str9 : str255; 
hPos, vPos, hor, ver : integer; 
X, y, Z1, z2 : real; 
rBox, ClipBox : rect; 
Width : Widhd!; 
leading : integer; 
LineNo : integer; 
ParagraphBegin : Point; 
Indent : integer; 
Paragraph : ARRAYL 1. .LinesInParagraph] 
OF str255; 
TxtPicRec : TTxtP icRec; 
TxtPicPtr : QDPtr; 
TxtPicHdl : QDHandle; 
TextClipRgn : RgnHandle; 
SaveClip : RgnHandle; 
fInfo : FontInfo; 


BEGIN 
SaveClip := NewRgn; 
GetClipCSaveCl ір); 
ClipRect(pRect); 
TextClipRgn := NewRgn; 


penNormal ; 


Tex tFont (geneva); 
TextSize( 10); 
TextFaceC[ 12; 


hor := (pRect.right - pRect. left) DIV 2; 
ver := (pRect.bottom - pRect.top) DIV 2; 
Width := Widhdl(NewHandle(sizeof (widpt2)2); 


Width^^.h := 10; 
Width**.v := 1; 
TxtPicPtr := @TxtPicRec; 


TxtPicHd] := @TxtPicPtr; 
TxtPicRec.tJus := LeftJust; 
TxtPicRec.tFlip := 0; (no flip) 
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TxtPicRec.tRot := 0; (no rotation) 

TxtPicRec.tLine := 2; (1 1/2 spacing) 

GetFontInfo(flnfo); 

leading := flnfo.descent + fInfo.ascent + 
fInfo.leading; 


Indent := 2; 
WITH fPlotDoc DO 
BEGIN 


x := -fXScale / 2; 
у := ТАРагап х x * x + (fBParam * x) 
+ fCParam; 
hPos := INTEGERCROUND(x * hor * 2 / fXScale + hor)); 
vPos := INTEGERCround(-y * ver * 2 / fYScale + уег)); 
71 := -fBParam / (2 х fAParam); 
z2 := (4 * fAParam * fCParam - 
(fBParam х fBParam)) / (4 * fAParam); 


END ; 

le := 2; 

tp := ver + (ver DIV 3); 

ri := 140; 

IF ri >= Chor + hor DIV 3) THEN 


5 


i := hor + hor DIV 3; 

bo := ver + ver - 2; 

setRect(rBox, le, tp - 14, ri, bo); 
ParagraphBegin.h := 4; 
ParagraphBegin.v := tp; 


(Graph Text) 
WITH fPlotDoc DO 


BEGIN 

stri := Int2Str(-fXScale DIV 2); 
str2 := Int2Str(fYScale DIV 2); 
str3 := Int2Str(fXScale DIV 2); 
str4 := Int2Str(-fYScale DIV 2); 


Peregraph[ 1] := СОМСАТС 
‘y=ax*2 + bx + с^, erString); 
Рагадгарһ 2] := CONCATC ‘a=’, 
Real2Str ing(fAParam, 1), 
f b=’, 
Real2String(fBParem, 1), 
¢ c=’ 
Real2String(fCParam, 1), 
erString); 
Paragraph([3] := CONCATC’x1=’, 
Real2StringCfRoot 1,2), 
V х2=”, 
Real2String(fRoot2,2), 
erstring); 
END ; 


CASE fPlotDoc.fResult OF 
1 
Peragraph[4] := 
СОМСАТС 
‘Two Real Roots, хі, x2’, 
erString); 
2: 
Paragraph[4] := 
CONCAT( Double Root’, 
erString); 
22 
Paragraph[4] := 
CONCATC ‘Two Complex Roots ‘, 
erstring); 
OTHERWISE 


END ; 

Paragraph[5] := CONCAT( Slope 0 = С”, 
Real2String(z1, 1), 
' ,' ,Real2String(z2, 1), 72”, 
crStr ing); 


PenNorma!; 
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BackColorCTQPlotApplicationCgApplication). 
fDefBack); 

ForeColor(TQPlotApplication(gApplication). 
fDefAxis); 


(Drawing Boundary} 
(Begin MacDraw Document) 


PicComment(picDwgBeg, 0, NIL); 


PicComment(picGrpBeg, 0, NIL); 

PicComment(SetL ineWidth, 
GetHandleSizeCHandle(Width)), 
HandleCWidth)); 


IF QDdevice = Display THEN 
FillRect(pRect, white); 
FrameRect(pRect); 


(Two Axis) 


PicComment(picGrpBeg, 2, NIL); 
moveto(O, ver); 

lineChor + hor, 0); 
movetoChor, 0); 

Тіпе(й, ver + ver); 
PicComment(picGrpEnd, 8, NIL); 


ForeColor(TQPlotApplication(gApplication). 
fDefGraph); 


(Plot Itsef } 


PicComment(picGrpBeg, Ø, NIL); 
movetoChPos, vPos); 
WITH fPlotDoc 00 
REPEAT 
x := x + fStep; 
у := fAParam * x х x + (fBParam * x) + fCParam; 
hPos := integer(round(x * hor * 2 / fXScale + hor)); 
vPos := integer(round(-y * ver * 2 / fYScale + ver)); 
WITH pRect DO 
IF (hPos < right) AND 
(hPos > left) AND 
(vPos < bottom) AND 
(vPos ? top) THEN 
LineToChPos, vPos) 
ELSE 
moveto(hPos, vPos); 
UNTIL x >= fXScale / 2; 
PicComment(picGrpEnd, 0, NIL); 


ҒогеСо1ог(Со1о0г5 (110; 


(Axis Text) 


moveto(4, ver + 14); 
DrawString(str1); 

moveto(hor - 40, 14); 
DrawString(str2); 

moveto(hor + hor - 50, ver + 14); 
DrawString(str3); 

moveto(hor - 40, ver + ver - 14); 
DrawString(str4); 


(Box ) 


PicComment(picGrpBeg, 0, NIL); 
PicComment(picGrpBeg, 0, NIL); 


PicComment(SetL ineWidth, 
GetHandleSizeCHandle(Width)), 
HandleC(Width2); 


IF QDdevice = Display THEN 
fillRect(rBox, white); 

frameRect(rBox); 

PicComment(picGrpEnd, 0, NIL); (of box) 
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GetClip(TextC1ipRgn); 
ClipBox := rBox; 
ClipRect(ClipBox); 


(Box Text) 
PicComment(TextBegin, sizeof(TTxtPicRec), 
Handle(TxtPicHd1)); 
FOR LineNo := 1 TO LinesInParagraph DO 
BEGIN 
moveto(ParagraphBegin.h, 
ParagraphBegin.v); 
moveCIndent, (LineNo - 1) * 
leading); 
DrawString(Paragraph[(LineNo]); 
END ; 
PicComment(TextEnd, 0, NIL); 
PicComment(PicGrpEnd, 0, NIL); (of Box/text) 
PicComment(PicGrpEnd, Ø, NIL); (of sel. all) 
picComment(picDwgEnd, 0, NIL); (of drawing) 


SetClip(SaveClip); 
disposHandle(handle(width)); 
DisposeRgn(TextCl1ipRgn); 
DisposeRgn(SaveClip); 

rin ( Laud ) 


PROCEDURE TQPlotV iew.SuperViewChangedS ize 
(delta: VPoint; invalidate: BOOLEAND; 
OVERRIDE; 
(x 
*This procedure changes the view size when 
x the window is resized. 
х) 
BEGIN 
(* 
*We only need to go through these 
* shenanigans if we are NOT displaying a page- 
x sized picture. This resizes the view’s extent 
* rectangle and invalidates the area, forcing the 
* view to redraw the picture in the new size. 
*) 
IF NOTCfOnePage) THEN 
BEGIN 
AdjustSize; 
ҒогсеКесган; 
END ; 
raed ( TQPlotView.SuperViewChangedS ize ) 


PROCEDURE TQPlotView.Resize (width, 
height: VCoordinate; invalidate: 
BOOLEAN); OVERRIDE; 
(ж 
*This procedure is called from AdjustSize. 
* It is here because when we toggle between Page 
x Size and Window Size plots, we need to tell the 
* view to redraw itself (because it changed size, 
* even though the window didn’t). 
х) 
BEGIN 
ForceRedraw ; 
INHERITED Resize(width, height, FALSE); 
ForceRedraw; 
END; { TQPlotView.Resize ) 


----------: 
PROCEDURE TQPlotView.Draw(area: Rect); OVERRIDE; 
(ж 


*This procedure is called to draw the view 
* when it needs to be drawn. The picture we 
* created before is ALWAYS drawn to take 
x up the entire window. 
x) 
VAR 
tRect: Rect; 
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BEGIN 


GetQDExtent(tRect); ( always draw pict to 
fill entire extent of the view } 
EraseRect(tRect); 
IF (fDrawing=NIL) THEN 
BEGIN 
fÜrawing :- OpenPicture(tRect); 
PrQDStuffCtRect, 1); 
ClosePicture; 
PenNorma] ; 
END ; 
DrawPicture(fDrawing, tRect); 
END; (TQPlotView.Draw ) 


SS 
— File UQPlot.r —— —) 


) 
/* Copyright € 1989 by Charles F. McMath. 
All rights reserved. */ 


ifdef Debugging 
include “Debug.rsrc’; 
#endif 

include “MacApp.rsrc’; 
include “Printing.rsre”; 
include *Dialog.rsrc"; 


include “QPlot” ‘CODE’; 


resource ‘BNDL’ (128) { 
'FGT3", 
0, 
( 'ICNÀ ^, 
(0, 128, 1, 129), 


); 


resource ‘FREF’ (128) ( 
‘APPL’, 0,4” 
); 


resource ‘FREF’ (129) ( 
е Р 


type 'FGT3' as ‘STR °; 


resource ‘FGT3’ (Ø) ( 
"€ by Dave Kelly & Dave Smith \пмег* 
“4 JAN 1988; " 
“ MacApp version by Chuck McMath” 


7 


resource ‘WIND’ (1001, purgeable) ( 
(45, 15, 445, 615), 
zoomDocProc, 
invisible, 
goAway, 
0x0, 
"ОО»»” 
); 


resource ‘view’ (1001, purgeable) ( 


root, ‘WIND’, ( 50, 20 ), ( 260, 430 ), 
sizeVariable, sizeVariable, shown, 
enabled, 
Window ( "TWindow^, zoomDocProc, 
goAwayBox, resizable, 
modeless, 
ignoreFirstClick, 
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); 


resource ‘view’ (1002, purgeable) ( 


) 
); 


resource ‘view’ (2000, purgeable) ( 
( /* array viewArray: 15 elements */ 


freeOnClosing, 
disposeOnFree, 
closesDocument, 
openWithDocument, 
dontAdaptToScreen, 
stagger, forceOnScreen, 
dontCenter, ‘QPLT’, *” ); 
‘WIND’, ‘SCLR’, (0,0), 
( 260-kSBarSizeMinus1, 
430-kSBarSizeMinus! ), 
sizeRelSuperView, 
sizeRelSuperView, 
shown, enabled, 
Scroller ( *TScroller’, 
vertScro] 1Bar, 
һог25сго11Ваг, 
0, 0, 16, 16, 
vertConstrain, 
horzConstrain, 
(6 8, 8, 8) ); 
‘SCLR’, IncludeViews ( 1002 ) 


root, ‘QPLT’, 

( 0, 0 ), ( 134, 414), 
sizeFixed, sizeFixed, 
shown, enabled, 

View ( *TQPlotView^) 


root, noID, 
( 100, 105 ), ( 150, 300 ), 
sizeVariable, sizeVariable, 
notShown, enabled, 
Window ( 
“TWindow”, 
documentProc, 
noGoAwayBox, 
notResizable, 
modal, 
ignoreFirstClick, 
freeOnClosing, 
disposeOnFree, 
doesntCloseDocument, 
dontOpenWithDocument, 
dontAdaptToScreen, 
dontStagger, 
dontForceOnScreen, 
center, 
noID, 
“Plot Parameters” 


), 
/* (2) */ 
root, 'PPRM', 


(0, 0), (150, 300), sizeVariable, 


sizeVariable, shown, disabled, 


DialogView ( ^TDialogView", “ok 


noID ), 
/* [9] */ 
‘PPRM’, “ok ^', 


(110, 230), (26, 45), sizeFixed, 


sizeFixed, shown, enabled, 
Button ( 

“TButton”, 

0р0, 

(1, 1), 

sizeable, 

notDimmed, 
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notHilited, 
dismisses, 
(0, 0, 0, 0), 
plain, 


0, 
(0х0,0х0,0х0), 
"^ 


‘PPRM’, а ', 
(30, 15), (20, 45), 
sizeF ixed, sizeFixed, 
shown, enabled, 
EditText ( 
“TEditText”, 
0b1111, 
(1, 1 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
(2, 2, 2, 2), 
plain, 


0, 
(0х0,0х0,0х0), 
"^ 


justLeft, 
т 17; 
unlimited, 

Øb 1111000000000 


0000000000 100000000 


); 
/* [5] */ 
‘PPRM’, b  ', 
(30, 100), (20, 45), sizeFixed, 
sizeFixed, shown, enabled, 
EditText ( 
“TEditText’, 
061111, 
(1, 1), 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
(2;:2, 2, 2); 
plain, 


0, 
(0x0 ,0x0,0x0) , 
е № 


justLeft, 
N _ i, 
unlimited, 

Øb 1 11100000000000 


00000000 100000000 


/* (61 */ 
'PPRM^, “ “, 
(30, 180),(20, 45), sizeFixed, 
sizeFixed, shown, enabled, 
EditText ( 
“TEditText”, 
001111, 
(1, 1), 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
(2, 2, 2, 2), 
plain, 
0, 
(0х0,0х0,0х0), 


justLeft, 
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"07; 
unlimited, 
Øb 1111000000000000000 


0000 100000000 


), 
/* (11 */ 
"PPRM', ‘step’, 
(80, 10), (20, 55), sizeFixed, 
sizeFixed, shown, enabled, 
EditText ( 
“TEditText’, 
061111, 
(1, 1), 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
(2, 2, 2, 2), 
plain, 


(дхй , 0x2 , 0x0) , 

justLeft, 

w 05”, 

unlimited, 
011110000000000000000 


000 100000000 


/* [8] */ 
‘PPRM’, ‘xscl’, 
(80, 100), (20, 50), sizeFixed, 
sizeFixed, shown, enabled, 
EditText ( 
“TEditText’, 
001111, 
(1, 1), 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
(2, 2, 2, 2), 
plain, 


8, 

(0x0 , 0x0 , 0x0) , 

justLeft, 

[ 4 10”, 

unlimited, 
001111000000000000000 


0000 100000000 


), 
/* [9] */ 
‘PPRM’, ‘yscl’, 
(80, 185), (20, 50), sizeFixed, 
sizeFixed, shown, enabled, 
EditText ( 
“TEditText’, 
001111, 
(1, 1), 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
(2, 2, 2, 2), 
plain, 


0, 
(0x0,0x0,0x0), 
"^ 


justLeft, 
^20", 
unlimited, 
Øb 111100000000000000000 


00 100000000 


д 
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/* [10] */ 

‘PPRM’, 'alab', 

(10, 35), (16, 20), 

SizeFixed, sizeFixed, 

shown, disabled, 

StaticText ( 
"TStaticText^, 
000, 
(1, 1), 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
(0, 0, 0, 0), 
plain, 
0, 
(0х0,0х0,0х0), 


JustLeft, 
“а” 
); 
/* [11] */ 
"PPRM^, ‘blab’, 
(10, 120), (16, 20), SizeFixed, 
SizeFixed, shown, disabled, 
StaticText ( 

*TStaticText"^, 

000, 

(1, 1), 

sizeable, 

notDimmed, 

notHilited, 

doesntDisniss, 

(0, 0, 0, 0), 

plain, 

0 


2 
(0х0,0х0,0х0), 
"^o 


д 

justLeft, 

“Б^ 
), 
/* [12] */ 
‘PPRM’, ‘clab’, 
(10, 200),(16, 20), sizeFixed, 
sizeFixed, shown, disabled, 
StaticText ( 

"TStaticText^, 

000, 

(1, 1), 

sizeable, 

notDimmed, 

notHilited, 

doesntDismiss, 

(0, 0, 0, 0), 

plain, 


0, 
(0х0,0х0 0х0), 
"^ 


justLeft, 
"eT 
2 
/* [13] */ 
‘PPRM’, ‘slab’, 
(60, 10), (16, 55), 
sizeFixed, sizeFixed, 
shown, disabled, 
StaticText ( 
“TStaticText”, 
000, 
(1, 1), 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
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(2, 0, 0, 0), 
plain, 


0, 
(0х0,0х0,0х0), 
wa 


7 
justLeft, 
) “step size” 
/* [14] */ 
‘PPRM’, ‘xlab’, 
(60, 95), (16, 55), 
sizeFixed, sizeFixed, 
shown, disabled, 
StaticText ( 
“TStaticText’”, 
000, 
(1, 1), 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
(0, 0, 0, 0), 
plain, 


g, 
(0x0 ,0x0, 0x0) , 
"^ 


justLeft, 
“x scale” 


), 
/* [151 */ 
'PPRM^, ‘ylab’, 


(60, 180), (16, 70), sizeFixed, 


sizeFixed, shown, disabled, 
StaticText ( 
*TStaticText^, 
0р0, 
(1, 1), 
sizeable, 
notDimmed, 
notHilited, 
doesntDismiss, 
(0, 0, 0, 0), 
plain, 
0 


д 
(0х0,0х0,0х0), 
"^ 


justLeft, 
“u scale" 
) 
) 
); 


resource ‘SIZE’ (-1) ( 
dontSaveScreen, 
acceptSuspendResumeEvents, 
enableOptionSwitch, 
canBackground, 

MultiF inderAware, 
backgroundAndF oreground, 
dontGetFrontClicks, 
ignoreChildDiedEvents, 
is32BitCompatible, 
reserved, 

reserved, 

reserved, 

reserved, 

reserved, 

reserved, 

reserved, 

"if qDebug 

275 * 1024, 

200 * 1024 

telse 

(250-32) * 1024, 
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(175-32) * 1024 
Yendif 


); 


resource ‘DLOG’ (1824) ( 
(100, 108, 318, 416), 
dBoxProc, 
-1, 
noGoAway, 
9x0, 
1024, 
“About Plotter...” 
7 


resource ‘DITL’ (1024, purgeable) ( 
( /* array DITLarrau: 5 elements */ 

/* (1) */ 

(112, 235, 141, 284), 

Button ( 
enabled, 
“ОҚ” 

), 

/* [2] */ 

(10, 88, 141, 289), 

StaticText ( 
disabled, 
“Plot Demo\n\nGraphs “ 
“Quadratic Equations\n*9” 
“үл” 1\n*2\n*3" 


/* [3] */ 
(10, 10, 96, 81), 
Picture ( 
disabled, 
128 
), 
/* (4) */ 
(154, 22, 208, 283), 
StaticText ( 
disabled, 
“This əpplication brought” 
“ to uou courtesu” 
“ of MacApp® 2.0." 
“ Copuright “1985-1988” 
“ Apple Computer, Inc." 


7 
/* [5] */ 
(149, 17, 211, 290), 
UserItem ( 
disabled 


) 
); 


resource ‘cmnu’ (1) ( 


textMenuProc, 
Ox7FFFFFFD, 
enabled, 
apple, 
(/* array: 2 elements */ 
/* C1) */ 
“About Plotter..”, noIcon, noKey, noMark, 
plain, cAboutApp; 
/* (2) */ 
“-” nolcon, noKey, noMark, plain, nocommand 


); 


resource ‘cmnu’ (2) ( 
2 
textMenuProc, 
allEnabled, 
enabled, 
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“File”, 
(/* array: 8 elements */ 

/* (1) */ 

*Plot.", noIcon, "P^, noMark, 
plain, cNew; 

/* [2] */ 

“-*, noIcon, noKey, noMark, plain, 
nocommand; 

/* [3] */ 

“Save”, noIcon, "S^, noMark, plain, 
cSave; 

/* (4] */ 

“Save As..”, noIcon, noKey, noMark, 
plain, 

cSaveAs; 

/* [5] */ 

“Page Setup..”, noIcon, "U^, поМагк, 
plain, 

cPageSetup; 

/* [6] */ 

*Print..^, noIcon, ^0”, noMark, 
plain, cPrint; 

/* [Т] */ 

4-4, noIcon, noKey, noMark, plain, 
nocommand; 

/* [8] */ 

*Quit^, noIcon, *Q^, noMark, plain, 
5” 


); 


resource ‘cmnu’ (3) ( 
3, 
textMenuProc, 
811Enabled, 
enabled, 
“Edit”, 
(/* array: 6 elements */ 
/* [1] */ 
*Undo^, noIcon, "Z^, noMark, plain, 
cUndo; 
/* [2] */ 
^-^, noIcon, noKey, noMark, plain, 
nocommand; 
/* [3] */ 
“Cut”, noIcon, ^X^, noMark, plain, 
cCut; 
/* [4] */ 
“Сору”, noIcon, “С”, noMark, plain, 
cCopy; 
/* [5] */ 
“Paste”, noIcon, V”, noMark, 
plain, cPaste; 
/* [6] */ 
*Clear^, noIcon, noKey, noMark, 
p cClear 


); 


resource ‘cmnu’ (4) ( 
4, 
textMenuProc, 
allEnabled, 
enabled, 
“Graph”, 
(/* array: 3 elements */ 
/* [1] */ 
“Graph”, noIcon, "Mx1B^, "M2x0A", 
plain, 
1201; 
/* [2] */ 
“Axis”, noIcon, "MOx1B^, “\0х0В*, 
plain, 1202: 
— [* [3] */ 
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“Background”, noIcon, "MOx 1B^, 
*MOxQC^, plain, 
1203 


) 
); 
resource ‘cmnu’ (5) ( 


textMenuProc, 
allEnebled, 
enabled, 
“Print Options”, 
(/* array: 2 elements */ 
/* (1) */ 
“Window Size", noIcon, “[“, noMark, 
plain, 
1301; 
/* [2] */ 
“Page Size”, noIcon, 41”, 
pm 1302 


); 


resource ‘cmnu’ C10) ( 
10 
textMenuProc, 
allEnabled, 
enabled, 
“Graph Colors”, 
(/* arrau: 8 elements */ 
/* [1] */ 
“Black”, noIcon, noKeu, noMark, 
plain, 10001; 
/* (2) ¥/ 
“White”, noIcon, noKey, noMark, 
plain, 10002; 
/* [3] */ 
“Кей”, noIcon, noKeu, noMark, 
plain, 10003; 
j* (41 */ 
“Green”, noIcon, поКеу, noMark, 
plain, 10004; 
/* 15] */ 
“Blue”, noIcon, noKey, noMark, 
plain, 10005; 
/* (6) ¥/ 
“Cyan”, noIcon, noKey, поМагк, 
plain, 10006; 
/* [Т] */ 
“Magenta”, nolcon, noKey, noMark, 
plain, 


noMark, 


10007; 
/* [8] */ 
*Yellow", noIcon, noKey, noMark, 
У 10008 


); 


resource ‘cmnu’ (11) ( 
j 
textMenuProc, 
al lEnabled, 
enabled, 
“Axis Colors", 
(/* array: 8 elements */ 
/* (1) */ 
“Black”, noIcon, noKey, noMark, 
plain, 11001; 
/* (2) */ 
“White”, noIcon, noKey, noMark, 
plain, 11002: 
/* [3] */ 
“Кей”, noIcon, noKey, noMark, 
plain, 11003; 


/* (4] */ 

“Green”, noIcon, noKey, noMark, 
plain, 11004; 

/* [5] */ 

“Blue”, noIcon, noKey, noMark, 
plain, 11005; 

/* (61 */ 

“Cyan”, поісоп, noKey, noMark, 
plein, 11006; 

/* [Т] */ 

“Magenta”, noIcon, noKey, noMark, 
plain, 

11007; 

/* [8] */ 

"Yellow", noIcon, noKeu, noMark, 
. 11008 


); 


resource ‘cmnu’ (12) ( 
12, 
textMenuProc, 
allEnebled, 
enabled, 
*Background Colors", 
(/* array: 8 elements */ 
/* [1] */ 
"Black", noIcon, noKey, noMark, 
plain, 12001: 
/* [21 ¥/ 
“White”, noIcon, noKey, noMark, 
plain, 12002; 
/* [3] */ 
“Кей”, noIcon, noKey, noMark, 
plein, 12003; 
/® (41 w/ 
| “Green”, noIcon, noKeu, noMark, 
plain, 12004; 
/* [5] */ 
“Blue”, noIcon, noKey, noMark, 
plain, 12805; 
/* [6] */ 
“Cyan”, nolcon, noKey, noMark, 
plain, 12006; 
/* (7) */ 
“Magenta”, nolcon, noKeu, noMark, 
plain, 
12007; 
/* (8) */ 
“Yellow”, noIcon, noKey, noMark, 
plain, 12008 
) 


); 
resource “cmnu (128) ( 


textMenuProc, 
allEnebled, 
enabled, 
“Buzzwords”, 
(/* array: 1 elements */ 
/* [1] */ 
“Page Setup Change”, noIcon, поКеу, 
noMark, 


) 
); 


resource “MBAR (128) ( 
| (1; 2; 3; 4; 5) 


2 


plain, cChangePrinterStule 


resource “MBAR (130) ( 
(10; 11; 12) 


451 


); 


resource ‘mctb’ (0) ( 


) 
); 


7 7 


( /* array: 4 elements */ 


0, 0, 0, 

65535, 65535, 65535, 
65535, 0, 65535, 
65535, 65535, 65535 


resource 'mctb^ (1) ( 
(1, 0 


) 
); 


д 

/* [1] */ 

( /* array: 4 elements */ 
0, 65535, 65535, 
65535, 65535, 65535, 
65535, 0, 0, 
65535, 65535, 65535 


), 
/* [2] */ 
1, 1, 
( /* array: 4 elements */ 
0, 0, 65535, 
0, 0, 65535, 
0, 0, 65535, 
65535, 65535, 65535 


), 

/* [3] */ 

1, 2, 

( /* array: 4 elements */ 
0, 0, 65535, 


) 


resource 'mctb^ (10) ( 
(10, 1, 


( /* array: 4 elements */ 
0, 0, 0, 
0, 0, 0, 
0, 0, 0, 
65535, 65535, 65535 


( уж array: 4 elements */ 
0, 0, 0, 


65535, 65535, 65535 


), 
/* [3] */ 
10, 3, 
( /* array: 4 elements */ 
65535, 0, 0, 
65535, 0, 0, 
65535, 0, 0, 
65535, 65535, 65535 


}, 
/* (4) */ 
10, 4, 
( /* array: 4 elements */ 
0, 65535, 0, 
0, 65535, 0, 
0, 65535, 0, 
65535, 65535, 65535 


), 
/* (51 */ 
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); 


) 


10, 5, 
( /* array: 4 elements */ 
0, 0, 65535, 
0, 0, 65535, 
0, 0, 65535, 
65535, 65535, 65535 


~ 


), 
/* [6] */ 
10, 6, 
( /* array: 4 elements */ 
0, 65535, 65535, 
0, 65535, 65535, 
0, 65535, 65535, 
65535, 65535, 65535 
), 
/* [7] */ 
10, 7, 
( /* array: 4 elements */ 
65535, 0, 65535, 
65535, 0, 65535, 
65535, 0, 65535, 
65535, 65535, 65535 


), 

/* (8) */ 

10, 8, 

( /* array: 4 elements */ 
65535, 65535, 0, 
65535, 65535, 0, 
65535, 65535, 0, 

) 65535, 65535, 65535 


resource 'mctb^ (11) ( 
( /* array MCTBArray: 8 elements */ 


/* (1) */ 

11, 1, 

( /* arrau: 4 elements */ 
0, 0, 0, 
0, 0, 0, 


0, 0, 0, 

65535, 65535, 65535 
уж (2) */ 
11, 2, 


( /* array: 4 elements */ 
0, 0, 0, 


0, 0, 0, 
65535, 65535, 65535 


11, 3, 
( /* array: 4 elements */ 
65535, 0, 0, 


65535, 0, 0, 
65535, 65535, 65535 


11, 4, 
( /* array: 4 elements */ 
0, 65535, 0, 
0, 65535, 0, 
0, 65535, 0, 
65535, 65535, 65535 


11, 5, 

( /* array: 4 elements */ 
0, 0, 65535, 
0, 0, 65535, 
0, 0, 65535, 


); 


) 


65535, 65535, 65535 


/* [6] */ 
11, 6, 
( /* array: 4 elements */ 
Ø, 65535, 65535, 
0, 65535, 65535, 
0, 65535, 65535, 
65535, 65535, 65535 


), 
/* [Т] */ 
11, 7, 
( /* array: 4 elements */ 
65535, 0, 65535, 
65535, 0, 65535, 
65535, 0, 65535, 
65535, 65535, 65535 


}, 

/* [8] */ 

11, 8, 

( /* array: 4 elements */ 
65535, 65535, Ø, 
65535, 65535, Ø, 
65535, 65535, Ø, 

) 65535, 65535, 65535 


resource 'mctb^ (12) ( 
( /* array MCTBArray: 8 elements */ 


/* (1) */ 
12, 1, 
( /* array: 4 elements */ 


( уж array: 4 elements */ 
0, 0, 0, 
0,0,0, 


0, 0, 0, 
65535, 65535, 65535 


65535, 0, 0, 
65535, 0, 0, 


, 9, 0, 
65535, 65525, 65535 


/* array: 4 elements */ 
0, 65535, 0, 

0, 65535, 0, 

0, 65535, 0, 

65535, 65535, 65535 


n 
/* [5] */ 
12, 5, 
( /* array: 4 elements */ 
0, 0, 65535, 
0, 0, 65535, 
0, 0, 65535, 
65535, 65535, 65535 


), 

/* (6) */ 

12, 6, 

( /* array: 4 elements */ 
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@, 65535, 65535, $^000А 0600 O1AF ААРА АСТА FEØØ 0А06 0003" 


0, 65535, 65535, $^5055 0558 @DFE 000В 0700 06А0 2A02 ABBA” 
0, 65535, 65535, $"80FF 0008 0700 0060 3603 5415 40FF 000В” 
65535, 65535, 65535 %%0700 BABS 6B06 ABEA COFF 0008 0700 005Ғ” 
Я $"D5FD 5555 40FF 0009 0100 @AFC AA00 COFF^ 
/* (7) */ $20009 0100 @DFC 5500 40FF 0009 0100 OFFC" 
12, T, $ “FF00 COFF 0002 F700 02Ғ7 0002 Ғ700 02Ғ7" 
( /* arrau: 4 elements */ $"0002 F700 02F7 0002 Ғ700 A000 8ҒАй 0083" 
65535, 0, 65535, $ FF” 
65535, 0, 65535, ); 
65535, 0, 65535, 
65535, 65535, 65535 resource “ICN8 ( 128) ( 
), ( /* arrau: 2 elements */ 
/* [8] */ /* [1] */ 
12, 8, $^0001 0000 0002 8000 0004 4000 0008 2000" 
( /* array: 4 elements */ $"0010 1000 0020 0800 0050 0400 0088 0200" 
65535, 65535, 0, $"0100 0100 0284 0080 0440 0240 0822 0420" 
65535, 65535, 0, $21410 0810 220А 1008 4084 3Ғ04 802А 4082" 
65535, 65535, 0, $"4001 8041 2003 3022 1005 C814 080Е 7F8F” 
65535, 65535, 65535 $"0412 3005 0221 0007 0140 8005 0080 6007" 
) %%0040 ІҒЕ5 0020 021F 0010 0407 0008 0800" 
) %%0004 1000 0002 2000 0001 4000 0000 80", 
); /* [2] */ 
%%0001 0000 0003 8000 0007 С000 000Ғ Е000" 
resource ‘PICT’ (128) ( %%001Ғ Ғ000 003Ғ Ғ800 007Ғ FCOO OOFF ҒЕ00" 
891, $*01FF ҒҒ00 O3FF FF80 OTFF FFCO OFFF FFE0" 
(195, 254, 281, 325), $"IFFF FFFÜ 3FFF FFF8 ТЕРЕ FFFC FFFF ҒҒҒЕ” 
$"1101 A000 82А0 008E 0100 0А00 0000 0002" $^TFFF FFFF 3FFF FFFE IFFF FFFC ЕЕЕ ҒҒҒҒ” 
$^D002 4098 000A 00С3 00Ғ8 00ҒҒ 0148 00C3" $"07FF FFFF Q3FF FFFF ІЕЕ FFFF @@FF FFFF^ 
$"00FE OOFF 0145 00С3 00ҒЕ 00ҒҒ 0145 0000" $"007F FFFF 003Ғ FEIF 00 1F FCO7 000Ғ F800" 
%%02Ғ7 0002 Ғ700 Ø2F7 0002 Ғ700 02F7 0002" $^0007 Ғ000 0003 Е000 0001 С000 0000 80" 
%Ғ700 02Ғ7 0002 Ғ700 02Ғ7 0002 Ғ700 02Ғ7" ) 
$"0006 Ғ000 000Е FCOO O7FD 0001 1Ғ80 FDOO" F; 
$"07FD 0001 7FCØ Ғ000 07FD 0001 FFFØ FD00" 
$^08ЕЕ 0002 O3FF ЕСЕЮ 0008 FE00 0207 FFFE" resource “ІСМЕ” (129) ( 
$"FDOO 09ҒЕ 0003 IFFF FF80 FE00 09ҒЕ 0003" ( /* arrau: 2 elements */ 
$"3FFF ҒҒЕй ҒЕй0 09ҒЕ 0003 ТЕРЕ FFF8 FE00" /* (1) */ 
$"0A02 0000 WIFE ҒҒ00 FCFE 0008 0200 0003" $’OFFF FEOO 0800 0300 0800 0280 0800 0240" 
$^FDFF FE00 0А02 0000 OFFD FFOO COFF 0008" $^0800 0220 0800 0210 0800 03Ғ8 0801 0008" 
%%0700 OO1F FFFF 3FFF EOFF 000В 0700 007Ғ” %%0880 0008 0801 0208 0840 0008 0801 0408" 
$*FFFE 1FFF F8FF 0008 0700 ØØFF FFFE 1FFF” %%0820 0008 0801 0808 0810 0008 0801 1008" 
$^FCFF 0008 0100 0ІҒЕ ҒҒ02 27FF FCFF 000В” $"0AAB AAAB 0809 2008 0804 4008 0803 8008" 
%%0100 O1FE FF02 FOFF F8FF 000В 0100 00ҒЕ” %%0800 0008 0801 0008 0800 0008 0801 0008" 
$"FF02 ҒЕТЕ FOFF 0008 0200 003Ғ FEFF 019Е* %%0800 0008 0801 0008 0800 0008 0801 0008" 
$"EOFF 0008 0200 00 ІҒ FEFF 01Е7 COFF 0008” $"0800 0008 0800 0008 0800 0008 OFFF FFF8", 
$"0200 003Ғ FEFF 01Ғ9 80ҒҒ 0008 0200 0033" /* (2) */ 
#“FEFF @1FE 80FF 000А 0200 0060 FDFF 00С0" #“@FFF FE00 @FFF FF00 @FFF FF80 @FFF FFCO" 
$"FF00 0807 0000 607F FFFF FCCO FF00 0807" $"0FFF FFEO OFFF FFFØ @FFF FFF8 @FFE FFF8" 
%%0000 601F FFFF F878 FF00 0807 0000 6007" $"0F7F FFF8 @FFE FDF8 ЕВЕ FFF8 @FFF FBF8" 
$^"FFFF FØF8 FF00 0807 0000 6001 FFFF FOF8" $"0FDD 7FF8 OFFA ВТЕ8 0ҒЕТ ОҒҒ8 OFEF FFF8" 
$ “FF00 0807 0000 6000 FFFF FOF8 FF00 0807" %%0074 5058 OFB7 DBF8 ØF7B BDF8 OEFD 7EF8" 
%%0000 6038 3FFF B050 FFOO 0А06 0000 607C” $"0FFF FFF8 OFFF FFF8 @FFF FFF8 ØFFF FFF8" 
$"0FFF 30FE 0008 0700 0060 F603 FE30 АВЕЕ* $"üFFF FFFB OFFF FFFB OFFF FFFB ДЕРЕ FFF8" 
$"0008 0700 0060 E301 FC30 50ЕҒ 0008 0700" $^0FFF FFFB ØFFF FFFB @FFF FFFB OFFF FFF8" 
$^0060 С000 7830 20FF 0008 0700 0060 0000" ) 
$* 1030 88FF 0008 0200 0060 FE00 0130 50ҒҒ” ); 


%%000А 0200 0060 ҒЕ00 0030 ҒЕ00 0802 0000" 
%“60ҒЕ 0001 30А8 ҒҒ00 0807 0000 6807 0700" (— x, 
%“8050 FF00 0А06 0000 681F 8ҒС0 BOFE 0008” (——- File UQPlot .MAmake 
%%0700 006С ТЕРЕ Ғ180 ABFF 000A 0200 0067" ----------------- 
$“ҒЕҒЕ 0030 ҒЕ00 0809 0000 63FF FFFE 31F4" 
$^1000 0809 0000 307F DFFO 6046 3000 0809" 
$^0000 381F 8FCO E045 5000 0809 0000 1С00" 
$"0001 C044 9000 0809 0000 0Е00 0003 8044" 
$"1000 0802 0000 0ТҒЕ FFFD 0009 0500 0001" 
$"FFFF FCFD 0008 ҒЕ00 0280 0004 FDOO 9800" 
$"0400 ҒҒ00 Ғ801 1901 4800 FF00 ҒЕ01 1901" 
$4500 FF00 ҒЕ01 1901 4500 0008 ҒЕ00 0280" 
$^0004 Ғ000 08ҒЕ 0002 FFFF ЕСЕЮ 0008 0200" AppName = QPlot 

$^0001 FEAA Ғ000 0802 0000 O3FE 55FD 000A" Creator = ‘FGT3’ 

$^0600 0006 FEAF ЕА80 ҒЕ00 0А06 0000 0083" 

$^5835 40ҒЕ 000A 0600 0018 0180 1АА0 FEQQ" = 
%“0А06 0000 3501 5015 50ҒЕ 000A 0600 006A" Р 
%%82А8 2AA8 ҒЕ00 0А06 0000 0570 5707 F4FE" елге 


) 


Copyright € 1989 Charles F. McMath. 
All rights reserved. 


This is the makefile. As uou can see, 

there’s not much to it. Because the application 
files are the ‘standard’ ones, MABUild will 
figure out (correctly) what needs to be done. 
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MacApp Workshop 


A Tale of Two Quadratic Plotters, 
Part II 


Another point of view 

When I started my efforts, I had to bring the program into the 
MPW environment, after all I started with someone else's code 
and wanted to cut and paste as much as I could. The first thing 
I did was run the source code through the MPW tool ‘MapOb- 
jects.’ This handy tool finds all Pascal UNITS defined in the files 
you give it to digest, then it goes about finding all PROCE- 
DUREs, FUNCTIONS and Objects that are defined. As it 
encounters the source code it remembers where (file and offset) 
it saw implementations of the procedures, then it writes out a 
database (called an ObjectMap) which can then be used by the 
Browser Desk Accessory to find and view procedures, functions 
and objects. Essentially you get a list of all Pascal UNITS, in 
alphabetical order, seen by MapObjects and for every by Pascal 
UNIT you can see, in alphabetical order, all PROCEDURES and 
FUNCTIONS contained in the UNIT. You can then click on the 
name of a PROCEDURE and the DA fetches it for you to view. 
Itis aread-only browser, but you can cut from the displayed text 
and paste it into your MPW file. (I also pass the latest MPW 
interfaces through MapObjects. This way I always have them 
online when I need to cut and paste a Toolbox call.) 

Displayed below is the output from doing a 'MapObjects - 
hvsm' on the original MacTutor Code. Note that where a line has 
two items on it, the second item is the name of the file containing 
that unit: 


Program 


QuadraticPlotter plotter 
QuadraticPlotter-Private plotter 
main 
initRects 
doUpdates 
doMulti 
doMouse 
doKeyDowns 
doActivates 
crash 
MainEventLoop 
InitMyWindow 
InitMyMenus 
InitMac 
Unit 


PlotGlobals PlotGlobals 
MyFileStuff myFileStuff 
doSaveAs 
doSave 
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MyPlotStuff myPlotStuff 
doQuit 
doMenubar 
doGrow 
doDrag 
doContent 
doAbout 
Misc Misc 
doMessage 
MyPrintStuff myPrintStuff 
doPrint 
doPageSet 
MyPrintStuff-Private myPrintStuff 
PrintMe 
solve solve 
solveit 
quad 
doPlot 
PrQDStuff 
solve-Private solve 
positivecalc 
negativecalc 
doDialog 
PlotMe 
The Browser turns out to be very helpful in understanding 
the MacTutor sources. I am not a veteran of previous MacTutor 
code so I did not know where Dave had decided to hide various 
parts of the code. I had expected that Dave's code would have 
some organizing principles that he used to decide where to put 
PROCEDURES and FUNCTIONS. The article pointed the way 
but you can also see it from the MapObjects output. The main 
program is contained in the file ‘plotter’. Code to initialize things 
was found in the Init routines in the main file ‘plotter’. What 
struck me was the pragmatic organization of the code. The 
principles that organized it seemed straightforward and general 
enough but I would never have guessed where the functionality 
would actually be found. I had forgotten how much my famili- 
arity with MacApp and its architecture caused me to make certain 
assumptions when looking at someone else’s code. 
For example, when I first received a copy of Chuck’s code 
I wondered if he had taken the time to implement the full page 
printing option. Knowing MacApp, I knew he would have 
created a DoSetupMenus and a DoMenuCommand to handle the 
functionality. So to check his code out I used the MPW search 
command to find all occurrences of DoSetupMenus in the .inc1.p 
file he sent and sure enough, I found he had two DoSetupMenus, 
one in TOPlotApplication and the other in TQPlotView. Select- 
ing the line with TQPlotView yielded exactly what I wanted to 
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know, it used a field (fOnePage) to place a checkmark beside a 
couple of menu entries that had associated command names of 
cPrintWS and cPrintPS which I deduced were probably print 
window size and print page size which corresponded to the 
original MacTutor code. Having such strong notions of where 
thingsare (and ought to be) makes it easy to maintain and extend 
someone else's source code. (Chuck's note: the reason Carl was 
able to find that section of my code so easily was partially 
because of the ‘MacApp pact’ I signed when I converted the code 
to MacApp —I agreed to place the code (actually I had very few 
other choices, being a good MacApp citizen and all) which deals 
with menu selections in the method DoMenuCommand, and Carl 
knows this.] 

In terms of external design features, the original plot pro- 
gram had two things that caught my attention. First was that the 
PICT was always drawn to fill the window and the second was 
that a modal dialog was put up to get the parameters for the 
equation. Ithought that always filling the window was a bit odd 
but, hey, I’m not really an engineer who plots quadratics all the 
time (if ever) so I felt that should be left alone. I actually had to 
do extra work to make the program behave this way. In the 
MacApp framework the simplest case would have been to setup 
a fixed size page or view area and then let MacApp scroll the 
image around for you. The modal dialog was probably an 
expedient design; there has to be a better user interface. I thought 
that it would be far better if the plot parameters could be entered 
іп the plot window. My design was simple: put all the fields from 
the modal dialog into a panel to the side of the plot area, let the 
user click and type new parameters at any time in a modeless 
fashion, and then let the user choose PLOT from the menu or 
press the ENTER key to cause the plot to occur. This simple 
design change allows multiple windows with their plots and 
parameters that created them to be showing at the same time. 


= Plot Untitled-1 


y7ax'2 + bx + c 

a=1.0, b=5.0, c=2.0 
x1=-0.438, х2--4.562 
Two Real Roots, x1, x2 
Slope 0 is (-2.5,-0.9) 


Figure 1. 


The original program only allowed the choice of 8 colors for 
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the plot. I thought as an example program that it should use the 
new Palette manger and let the user color as many parts of the plot 
with any color. Also I thought it would be пісе to allow for the 
selection of fonts and typestyles using the hierarchical menus. 
Besides, I could easily cut and paste all these features from the 
MacApp samples. 

In starting my port of the code I was going to use an external 
data structure to hold the pertinent data. After I started the design 
it became obvious that if I did a little bit of encapsulation it would 
be a good example of the right path to follow and clearly show the 
advantages of using Objects just like in Chuck’s program; I gave 
the original plot program’s data to the appropriate object to 
manage. 

As Chuck pointed out, there are always three methods you 
will override: TApplication.DoMakeDocument, which creates 
the appropriate type of Document object; 
TDocument.DoMakeViews which creates the appropriate type 
of View and window objects and finally TView.Draw which 
Draws the contents of a view in your window or on the page. 

I had to declare a Document type (TPlotDoc) that DoMake- 
Document could bring into existence. This document would hold 
the plots we would be writing to disk. The files created by this 
document would be readable with MacDraw and able to be 
placed into PageMaker. In order to read back these files I 
implemented a DoRead for TPlotDoc. Granted, it is a simple 
minded effort but it shows where it should be done. To properly 
implement writing and reading the plot parameters should also be 
written and read back. 

When a document is created its DoMakeViews method is 
called to create the views that will display the data in the 
document. In МасАрр 2.0 you can create views by doing a NEW 
for each view component and setting up the data structures, or 
you can (preferably) create resources that describe your views 
and let MacApp read them, create the objects and fill in their data 
structures. These resources are best created using Apple's 
ViewEdit. ViewEdit knows about MacApp view resources and 
lets you build and arrange on screen the view components that 
will make up your displays. It is indispensible in creating 
Applications with MacApp 2.0. 

In looking at the view hierarchy, we start with a window 
which is handled by a standard TWindow. In the window is a 
dialog handled by TPlotDialog. The dialog contains two display 
clusters and a scroller. The two clusters contain Static Text and 
NumberText view items that are used for collecting the equation 
coefficients and the plot parameters. The scroller contains the 
plot view which is handled by a TPlotView. The plot view 
contains a subview for holding the solution text box. Itis handled 
by a TSolutionView. 

This hierarchy of views are brought into existence by 
TPlotDoc's DoMakeViews call to NewTemplateWindow. As 
each componentof the view hierarchy is brought in existence, the 
associated object which will handle it is found and created by 
DoCreateViews. 

For the TStaticText and TNumberText views MacApp 
handles all the display and collection of keystrokes. MacApp 
2.088 does not have facilities for handling NumberViews with 
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Real numbers, an oversight in the rush to get MacApp 2.0 out the 
door. Calvin Cock wrote an article (and contributed the code and 
resources) for publication in the Dec ’88 Frameworks describing 
the a new view called TExtendedText which handles real num- 
bers (plug: join the MacApp Developer’s Association and 
receive Frameworks). Instead of reinventing the wheel, I used 
Calvin’s ExtendedText Views in the Clusters. 

Here is asummary of the view hierarchy which produced the 
window in Figure 1: 

соА ExtendedText 


TExtendedText 1.0 


соВ  ExtendedText 
TExtendedText 5.0 


сос  ExtendedText 
TExtendedText 2.0 


Cool Cluster TCluste 
Coefficients 
VW13 SialicText 


TStaticText а = 


VW14 ЅайстТех 
Т91аСТехі b = 


VW15 StaticText 
TStaticText с = 


DLOG  DialogView step ExtendedText 
TExtendedText 0.25 


xAxs NumberText 
TNumberText 10 


yAxs NumberText 
TNumberText 20 


Cdsp Cluster 
TCluster Display 
VW17 SialicText 


TStaticText step 


VW18 SialicText 
TStaticText X AXIS 


VW19 SiaticTexi 
TStaticText Y AXIS 


piot View TPloiView азм View 
TSolutionView 


sc Scroller 
Т5стойег 


Іп what I would call а fairly straightforward МасАрр ар- 
proach, TPlotDoc holds the parameters for the plot and TPlotDia- 
log holds the PicHandle generated from the original data struc- 
ture and does the display of the PICT. TPlot View and TSolution- 
View do all the work of actually drawing the PICT. Further work 
could be done on encapsulating and distributing the plotting and 
display. In particular, PRQDStuff from the original was a fairly 
large routine that did all the drawing work. I thought it might be 
proper to split it apart into a controlling object and objects that 
drew parts of plot. Not to go overboard, but to illustrate the point, 
I chose to have TPlotDialog create the wrapper and have it call 
the appropriate component parts that composed the PICT. 
TPlotDialog sets up the PICT and asks the other objects that it 
knows draw into it. It should be possible with the framework I 
have provided to move each AXIS and its labeling into separate 
views that can be setup independently. 

The current design does not utilize any of the MacApp 
framework to do interactive graphing. If the design of the 
program changed not to include re-scaling the PICT to the 
window, it would be possible to create an interaction with the 
PlotView. For example, you could grab the plot and move it 
around to show how the coefficients vary. 
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Given how easy it is to create multiple windows and docu- 
ments, it would be easy to create plot types and custom windows 
for different equations. To do this would require that you create 
new types of plot and view objects then override MacApp’s 
OpenNew method to create the desired new kind of plot docu- 
ment and window. 

As Chuck stated MacApp provides a command mechanism 
for undo and redo. If you look at the menu handling code for 
changing the plot color and text you will see how I have 
implemented Undo/Redo by saving and restoring the plot char- 
acteristics. I did not go all the way by invaliding the Plot and 
forcing a redraw instead I, like the Daves, wait until the next plot 
is drawn. If you look at TPlotDialog. DoKeyCommand you will 
see how easy it would be to have TPlotDoc.DoMenuCommand 
force a redraw. 


Analysis 
Now that we have each discussed our programs, we need to 
sit back a little and see just what we got out of MacApp. While 
Carl’s version is obviously an improvement given the number of 
features he added, the benefits of Chuck’s version are not so 
obvious. So Chuck re-takes the floor to convince you he's done 
a good job. 


How much time do we spend doing things? 

With all of the preceding discussion of my objects, it may 

seem that we are doing a lot of work in what is admittedly a simple 
application. Let's see if this is the case. I have analyzed the 
original and my code to see what percentage of code is used for 
different functions. This analysis is not perfect in that the original 
and new versions were written by different people, and therefore 
it does not allow for different programming styles, but still, the 
end application is the same (or as similar as a MacApp and 
non-MacApp application can be), so we can get an idea of where 
we spent our time. I split the source code into five different 
categories: 

* user interface: the Macintosh look — windows, menu setup 
and enabling, the ‘generic’ Mac portion. What 
code was necessary to make the application 
look like a Macintosh application? Note that 
this does not include the code to actually 
accomplish anything; that's in the next sec- 
tion. 

° interaction: the portion of the code that handles any user 
interaction & event processing. Anything that 
was written to handle interaction between the 
user and the application was assigned here. 

° input/output routines: any code involved with actually 
reading or writing data to the disk. This 
portion also includes code used to print the 
window, since I considered that an output 
operation. 

* program processing: this portion of code is anything that 
needed to be written to calculate or determine 
anything. This code does not have any corre- 
sponding on-screen elements. 
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e initialization and other: this category was used for all 
pieces of code that I couldn't assign anywhere 
else. 


Chart 1 shows for each category: the number of lines of code 
written for each version, and Chart 2 the percent of the total code 
that each section represents (comments and blank lines were 
removed before the count was made; so this is only counting 
executable code; 1405 for the original and 705 for MacApp). 

Chart 1: Lines of Code comparison: Original vs. 
MacApp 


Number of Lines of Code 


W original Plot BB MacApp Plot 


Input/Output 


o8 Š Š Š Š 8 


Processing User 
Interface 


Interaction Other 


The first difference that should jump outat you is the number 
of lines of code written. The MacApp version has half the 
number of lines as the non—MacApp version. Not only are there 
fewer lines, but the MacApp version has more features than the 
Original version — it allows multiple windows on the screen and 
scrolls the window contents, to name two. In addition, the 
MacApp feature follows Apple's user interface guidelines more 
closely in the page size/window size feature of the plot. In the 
original version, selecting *window size' changes the printed 
output, but does not change the display in the window — 
violating the WYSIWYG principle (What You See Is What You 
Get). So there's another area in which the MacApp program 
outperforms the original one. Still another area in which the 
MacApp version improves on the original is in menu handling. 
The original version has the Edit menu always enabled, even 
though those menu items do not apply to anything displayed in 
the window; you can also erroneously try to save or print before 
you have a plot window on the screen. Again, these operations 
violate the user interface guidelines — only appropriate menu 
items should be enabled. Yet the MacApp version does enable 
all of its menu items correctly. Why? Because of the design of 
MacApp. 

It's interesting to compare how time was spent in creating 
the two versions (assuming that the code was written at a constant 
rate. Iknow this is notan entirely rational assumption, but it's all 
we have to go on). I've been talking about how MacApp helps 
you by implementing the standard user interface elements, but 
looking at the chart you see that the MacApp program has four 
times as much user interface code (relatively speaking). Does 
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this mean that I was lying? I sure hope not! The reason for so 
much user interface code in the MacApp version is that there is 
a fixed amount of overhead associated with handling menu, 
mouse, and key events. This overhead is in the form of proce- 
dures which must be overridden to provide for the user interface 
processing. In addition, each object which handles these events 
must override the appropriate methods to provide the processing. 
Writing the code for all of these overrides adds up. However, 
once the procedures are overridden, adding more functionality to 
the processing is simple and does not require much more code. 
On the other hand, look at the amount of code we wrote to deal 
with interaction — the MacApp implement spent only half as 
much time implementing its interaction code. This is because we 
build upon the foundation that MacApp provides, and only have 
to add code to support the extra functionality we wish to provide. 
MacApp takes care of the normal interaction. 


Percent of Code per Task 
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Chart 2: Percent of Code: Original vs. MacApp 


This application is somewhat unusual in that the amount of 
‘pure’ processing code is rather small, although it's interesting 
that the relative amount of processing code is constant. One last 
thing to note is the amount of code in the ‘Other’ category. As 
I categorized the source code for the MacApp version, I realized 
that much of the code fell into this category. That’s because 
MacApp programs spend a lot of time initializing objects, creat- 
ing windows and views and documents, and doing a lot of things 
that are difficult to categorize. 


Chart 3 shows the amount of code that came directly from the 
original version to the MacApp version. The first column is the 
number of lines of code that was directly cut and pasted from the 
old version to the new. The second column is the total number 
of lines in the new category. The third column shows the 
percentage of each category that the old code makes up. This 
Chart is instructive in that it shows how much of your non 
MacApp program you will be able to reuse. It shouldn’t be 
surprising that none of the interaction or user interface code was 
transferable; it’s a little more surprising that none of the ‘other’ 
code was applicable. If you think about it, however, the MacApp 
‘other’ category is made up of code which is pretty specific to 
MacApp — object creation and initialization, and the object 
definitions. This code could not have come from the original 
program. 
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# Lines Taken Totalin New % of New 


Input/Output 181 211 86 
Interaction O 108 0 
Other 0 221 0 
Processing 48 48 100 
User Interface 0 117 0 
Totals 229 705 N/A 


Chart 3: Code requiring no conversion 


As you can see, all of the processing code used in the 
MacApp program came directly from the original version. This 
should give some weight to my assertion that in a MacApp 
program you need to concentrate on the unique portion of your 
application — for indeed, in the plotter application, the process- 
ing is the unique portion. And note also that most of the input/ 
Output routines came directly from the original version. Most of 
this code is related to creating and printing the PICT, and of 
course remains the same no matter whether you're using 
MacApp or not. 

The bottom line here, though, is that the MacApp version 
only required 50% as much code as the original version; and fully 
one-third of that code was lifted directly from the original, which 
means that the MacApp version only had around 500 new lines 
of code — one third as much as the original. And this does not 
yield a program that is crippled or partially functional, it yields 
a program that conforms to the user interface guidelines, is fully 
functional (within its design), and is a good bet to run on future 
Macintosh architectures (not to mention A/UX). This is the big 
win we get from MacApp: not something for nothing, but more 
results for less work. Sure, you have to change your thinking, but 
all I can say is this: look at the bottom line. 


Conciusion 

So there you have it — two views of a MacApp conversion 
effort, from two slightly different viewpoints. Although the two 
MacApp programs may seem quite different, they are much more 
similar to each other than either is to the original effort. If Carl 
and I swapped our two MacApp programs and each had to add a 
feature to them, we would be able to much more easily than if we 
were to try the same on the original program. All MacApp 
programs share a structure, an organization; different programs 
do similar things in the same place. Reusing code from one 
MacApp program to another is increased. You don't have to 
spend time searching for the procedure or function you want — 
you will know where to find it. 

We hope you have some idea of the benefits of MacApp and 
that you'll not only get more done, but you'll get it done more 
quickly (once you become a MacApp citizen), and your final 
product will be a real professional job. MacApp is the wave of 
the future — catch it today! [Aw Come-on Chuck, knock it off.] 
UPlot.p Plot UNIT FILE 
(La-,body*,h,o- 100, r*,rec*, t=4,u+, 8+, j220/57/1$,n*1) 

( The above is the official MacApp PasMat Style statement .What 


you don’t use pasmat to make all your source code conform to 
your company’s Cor personal) standard for source code style? ) 
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(Copyright € 1986-1988 Apple Computer, Inc. 
All rights reserved.) 

(Copyright € 1989 by Software Architects, Inc. 
All rights reserved.) 

(Portions Copyright € 1988 MacTutor 
All rights reserved.) 


((f-1) 
(* 

This is a veru small sample application which uses concepts 
and program fragments presented in the February 1988 MacTutor 
Plot Article. 

By looking at this program you may be able to gain a better 
understanding of how to cast a conventional program into the 
MacApp “Application Framework” or (Class structure depending 
upon whose jargon you wish to use). 
In the tradition of MacApp it defines the basic three Class 
Cobject) overrides: 
TPlotApplication.DoMaekeDocument- Launches appropriate type of 
Document object. 
TPlotDoc.DoMakeViews — Launches appropriate type View and 
window objects. 
TPlotDialog.Draw - Calls it sub components to draw the 
contents of a view. 

TPlotView - To actually plot the thing 

TSolveView - To draw the solution text box 
In addition it def ines commands unique to the plot program. 
See the text of the accompaning article for detials. 
*) 
([f+]) 


UNIT UPlot; 
INTERFACE 
USES 
( ° MacApp - this includes all of the things 
necessaru from the MacApp Libraru ) 
UMacApp, 


( 0 Building Blocks } 
UDialog, UPrinting, UExtendedText, 


( O Implementation Use ) 
SANE, ToolUtils, Fonts, Resources, 
Script, PickerIntf, Packages; 


CONST 
kSignature = ‘Plot’; 
( Application signature} 
kFileType = ‘PICT’: 


( File-type code used for document files 
created by this application) 
kPlotDialog = 1010; 


( MacApp uses a very useful technique for seperating menu 
item numbering from what you want done by chosing a menu item. 
See MacApp manual pggs xxx-xx for full details. Work is done 
in MacApp with commands. Each command is assigned a unique 
number. For example Save is 30 and SaveAs is 32. Numbers 
below 1200 are reserved for MacApp. In this Application we 
have chosen a command numbering scheme that makes life easy: 
Application Commands- 1400 


Font styles = 2000 
Font sizes - 2100 
Font just - 2200 
Font fonts - 2300 
Hierarchical Menus = 2400 
Plot colors - 2500 
) 
( the command to cause a plot to happen ) 

cPlotIt = 1401; 


( Command numbers for tupestule attributes ) 
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cPlainText = 2001; TextCenter = 154; 
cBold = 2002; 
cItalic = 2003; (postscript comments) 
cUnderline = 2004; SetLineWidth = 182; 
cOutline = 2005; PostScriptBegin = 190; 
cShadow - 2006; TextIsPostscript = 194; 
cCondense = 2007: PostScr iptEnd = 191; 
cExtend = 2008; 
( The size of a MacDraw Header ) 
( Command numbers for font-size commands ) kHeaderSize= 512; 
cSizeChange= 2100; 
cSizeBase = 2100; TYPE 
cSizeMin = 2109; QuadraticTupe = (NotSolved, RealRoots, 
cSizeMax = 2124; SingleSolution, ComplexRoot); 
( 2101-2197 reserved for font sizes 1-97 pts. ) (specifications of text display) 
cSizeGrow = 2198; PlotSpecs = RECORD 
cSizeShrink= 2199; theTextFont: $tr255; 
theFontNum: INTEGER; 
( Command numbers cover other stylistic changes ) theTextFace: Style; 
cJustChange= 2200; theTextSize: INTEGER; 
cJustLeft = 2201; theJustification: INTEGER; ( text ) 
cJustCenter= 2202; theTextColor:  R6BColor; ( label color ) 
cJustRight = 2203; theGraphColor : RGBColor; 
cFontChange= 2300; theAxisColor: RGBColor; 
theBackColor: RGBColor; 
( Command numbers for the hierarchial menu ) END; 
cStyle = 2401; 
cSize = 2402; PlotSpecsPtr = “PlotSpecs; 
cFont = 2403; PlotSpecsHd] = ^PlotSpecsPtr; 
cColor = 2404; 
( Object Definitions } 
( Command numbers for changing colors ) (—————ə>əƏ——əƏəpB°',) 
cColorChange = 2500; TPlotApplication = OBJECT (TApplication) 
cColorText = 2501; 
cColorBackground = 2502; ( Initialize application and globals. ) 
cColorGraph= 2593; PROCEDURE TPlotApplication.IPlotApplicationC 
cColorAxis = 2504; itsMainFileType: OSTupe); 
( Constant for amount to relative ( Launches a TPlotDocument ) 
size text selection ) FUNCTION TPlotApplication.DoMakeDocument( 
kRelSizeAmount = 4; itsCmdNumber: cmdNumber): TDocument; 
OVERRIDE; 
( Constants for the prompts string list ) 
kPromptsRsrcID = 1001; PROCEDURE TPlotApplication.IdentifySof tware; 
kColTextPrompt = 1; OVERRIDE; 
kColBackPrompt = 2; PROCEDURE TPlotApplication.FieldsC 
kColGraphPrompt = 3; PROCEDURE DoToField(fieldName: Str255; 
kColAxisPrompt = 4; fieldAddr: Ptr; 
fieldType: INTEGER)); 
( Menu numbers } OVERRIDE; 
mFont = 10; END; ( TPlotApplication } 
( Menus displayed on hier. menu system } 02-----------”) 
kHierDisplauedMBar= 131; TPlotDoc = OBJECT (TDocument) 
fPlotDialog: TPlotDialog; 
( Menus displayed on non-hier. system } fPlotSpecs : PlotSpecs; 
kNonHierDisplayedMBar = 128; fFOldPlot : PicHandle; 
( Offset added to non-hier menu cmds to get } ( coefficients to our quadratic equation } 
kHierMenuOffset = 1000; faParam : Real; 
( ‘view’ resource for default values } fbParem : Real; 
kViewRsrcID = 1005; fcParam : Real; 
( PICT comments for our plot and text box ) ( plot displau parameters ) 
(selected MacDraw comments) fstepParam : Real; 
picDwgBeg = 130; fxParam : INTEGER; 
picDwgEnd = 131; fyParam : INTEGER; 
picGrpBeg = 140; 
picGrpEnd = 141; ( the solutions to our quadratic } 
Tex tBegin = 150; fistRoot : Real; 
TextEnd = 151; f2ndRoot : Real; 
StringBegin = 151; 
Str ingEnd = 153; fRootType : QuadraticType; 
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( setup for the document to hold the plot ) TSolutionView = OBJECT (TView) 
PROCEDURE TPlotDoc. IPlotDocument; fPlotDoc : TPlotDoc; 
fSolveRect : Rect; 
( For new doc or revert initial state ) 
PROCEDURE TPlotDoc.DoInitialState; OVERRIDE; ( Add to pict we will draw on the screen or printed page } 
PROCEDURE TSolutionView.AddToPict(picRect:Rect); 


7 


( Generate command to change Look of а plot } 
FUNCTION TPlotDoc.DoMakePStuleCmd( 


itsStyle:PlotSpecsPtr; itsCmdNumber :CmdNumber): TPStuleCmd; TPlotDialog = OBJECT CTDialogView) 
fPlotSize : VPoint; 
( create all the views needed for document ) fPlotView : TPlotView; 
PROCEDURE TPlotDoc.DoMakeViews(forPrinting: BOOLEAN); fSolutionView: TSolutionView; 
OVERRIDE; fPlotDoc : TPlotDoc; 
fPlotPICT : PicHandle; 
( calculater how much disk space this 
document will need ) FUNCTION TPlotDialog.DoKeyCommand( 
PROCEDURE TPlotDoc.DoNeedD iskSpace( ch: CHAR; aKeyCode: INTEGER; 
VAR dataForkBytes, rsrcForkBytes: LONGINT); VAR info: EventInfo): TCommand; 
OVERRIDE; 
OVERRIDE; 
( read the data for this document ) FUNCTION TPlotDialog.DoMenuCommand( 
PROCEDURE TPlotDoc.DoRead( aCmdNumber : CmdNumber ): ТСоттага; 
eRefNum: INTEGER; rsrcExists, OVERRIDE; 
forPrinting: BOOLEAN); OVERRIDE; 
PROCEDURE TPlotDialog.DismissDialog( 
( write the data for this document } dismisser: IDType; flashDismisser: BOOLEAN); 
PROCEDURE TPlotDoc.DoWriteCaRefNum: INTEGER; OVERRIDE; 
makingCopy: BOOLEAN); OVERRIDE; 
PROCEDURE TPlotDialog.Draw(area: Rect); 
( given a Menu choice handle or pass it on ) OVERRIDE; 
FUNCTION TPlotDoc .DoMenuCommand( 
aCmdNumber: cmdNumber): TCommand; PROCEDURE TPlotDialog.EachSubV iew( 
OVERRIDE; PROCEDURE DoToSubV iewC 
theSubView: TView2); 
( setup the menus for the document ) OVERRIDE; 


PROCEDURE TPlotDoc.DoSetupMenus; OVERRIDE; 
PROCEDURE TPlotDialog.PlotNDrawPICT; 
( given the parameters of our 


document calculate a solution } PROCEDURE TPlotDialog.GetPlotValues; 
PROCEDURE TPlotDoc.SolveQuadratic; 


PROCEDURE TPlotDialog.DoSetupMenus; OVERRIDE; 
PROCEDURE TPlotDoc.ChangeBackColor( 


newColor: RGBColor); END; 
($IFC qDebug) TPStyleCmd = OBJECT (TCommand) 
PROCEDURE TPlotDoc.Fields( fPlotDialog : TPlotDialog; 
PROCEDURE DoToF ieldC fOldPlotSpecs: PlotSpecs; 
fieldName: Str255; fNewPlotSpecs: PlotSpecs; 
fieldAddr: Ptr; 
fieldType: INTEGER)); { Initialize the command; if unsuccessful, 
OVERRIDE; signalled by Failure mechanism } 
($ENDC) PROCEDURE TPStyleCmd. IPStyleCmdC 
itsPlotDialog:TPlotDialog; 
END; ( TPlotDoc ) itsNewStyle:PlotSpecsPtr; 
itsCmdNumber: CmdNumber ); 
TPlotView = OBJECT (TView) 
fPlotDoc : TPlotDoc; PROCEDURE TPStyleCmd.DoIt; OVERRIDE; 
PROCEDURE TPStyleCmd.RedoIt; OVERRIDE; 
( Add to the pict we will draw on PROCEDURE TPStyleCmd.UndoIt; OVERRIDE; 
the screen or printed page ) END; 
PROCEDURE TPlotView.AddToPict(picRect:Rect); 
VAR 
( A convenience routine ) gÜef au1tSpecs: PlotSpecs; 
PROCEDURE TPlotView.GetQDFrame( ( & Menu Management Global ) 
VAR frameRect :Rect); gMenuOfs: INTEGER; 
( Convenience, fetching string from resource ) 
( The design says the plot fills the gPromptString: 517255; 
window, therefore when we ere 
resized we must invalidate ourselves) IMPLEMENTATION 
PROCEDURE TPlotView.ResizeCwidth, (IMPLEMENTATION) 
height: VCoordinate; invalidate: BOOLEAN); (—— 
OVERRIDE; ($S ARes) 
END; ( Generalllu useful routines ) 
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FUNCTION GetPromptCindex: INTEGER): StringPtr; ($IFC qTrace) ($0**) ($ENDC) 
BEGIN ($ENDC qDebug) 
GetIndStringCgPromptStr ing, 


kPromptsRsrcID, index); (—  — O —.—VY 
GetPrompt := @gPromptString; ($S AreadFile) 
END; PROCEDURE ReadBytesCtheRefNum: INTEGER; 
Size:LONGINT; buffer: Ptr); 
FUNCTION Real2Str(CaReal: Real; theDigits: INTEGER): Str255; ( Utility for reading data from a f ile ) 
VAR aStr : DecStr; 
form: DecForm; BEGIN 
BEGIN Fail0SErr(FSRead( theRefNum, size, buffer)); 
form.style := FixedDecimal; END; 
form.digits := theDigits; 
Num2Str(form, aReal, aStr); ( ) 
Real2Str := aStr; ($5 AWriteFile} 
END; PROCEDURE WriteBytes(theRefNum: INTEGER; 
Size: LONGINT; buffer: Ptr); 
($IFC qDebug) ( Utility for writing data to a file. ) 
($1FC qTrace) ($0+) ($ENDC) BEGIN 
( In the final version of MacApp 2.0 there will some kind of FailOSErrCFSWriteCtheRefNum, size, buffer)); 
support for REAL numbers in text entry fields, for now we use END; 
Calvins Cock’s code from the Dec ’88 Frameworks ) | l 
PROCEDURE MyFieldToString(theData: Ptr; ($5 AInit) 
fieldType: integer; VAR theString: str255); 
CONST PROCEDURE TPlotApplication. IPlotApp] ication 
DecPrec = 2; itsMainFileType: 05Туре); 
( Change if you want more decimal precision ) VAR 
TYPE fontName : Str255; 
TAlias - RECORD aTEView: TTEView; 
CASE integer OF 
bReal, bSingle: CasReal : Real); BEGIN 
bDouble: CasDouble : Double); 
bExtended: CasExtended : Extended); ( qNeedsHierarchialMenus is a MacApp compile time flag you 
T END; can set which will require the use of Heirarchical Menus ) 
alias : *TAlias; ($IFC NOT qNeedsHierarchialMenus) 
aDecForm : DecForm; IF NOT gConf iguration.hasHierarchicalMenus THEN 
X : Extended; BEGIN 
NumStr : DecStr; gMBarDisplayed := kNonHierDisplaygedMBar; 
BEGIN gMenuOfs := Ø; 
alias := PointerCtheData); END 
WITH alias" DO ELSE 
CASE fieldType OF ($bENDC) 
bReal, bSingle: BEGIN 
BEGIN gMBarDisplayed := kHierDisplayedMBar; 
aDecForm.style := FixedDecimal; gMenuOfs := kHierMenuOffset; 
aDecForm.digits := DecPrec; END; 
x := asReal; 
Num2StrCaDecForm, x, NumStr); IApplicationCitsMainF ileTgpe); 
theString := str255(NumStr); 
END; ( Do not setup the menus if we were started up with the 
bDouble: request to print ) 
BEGIN IF NOT gFinderPrinting THEN 
aDecForm.style := FixedDecimal; BEGIN 
aDecForm.digits := DecPrec; AddResMenuCGetMHandleCmFont?, ‘FONT’); 
x := asDouble; 
Num2StrCaDecForm, x, NumStr); SetStyleCcBold, [bold]); 
theString := str255C(NumStr); SetStyleCcUnderline, [underline1); 
END; SetStyleCcItalic, [italic]; 
bExtended: SetStyleCcOutline, [outline12; 
BEGIN SetStyleCcShadow, [shadow]); 
eDecForm.style := FixedDecimal; SetStyleCcCondense, [condense]); 
aDecForm.digits := DecPrec; SetStyleCcExtend, [extend1); 
x := asExtended; END; 
Num2StrCaDecForm, x, NumStr); 
theString := str255(NumStr); ( This is an exemple of questional code reuse. We know that 
END; TTEVIEWS holds lots of info about fonts, sizes and color and 
OTHERWISE StdFieldToString( theData, we have the Viewedit tool at our disposal, so why not use it 
fieldType, theString); to create a useful resource to get our initial values from 
END; instead of hard-wiring the defaults. The technique here is to 
END; define a TTEView resource and use all those great fields that 


you can setup with viewEdit as the defaults, then steal the 
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values from the TTEVIEW object and trash the TTEView once all 
the work is done. ) 


(fetch the resource} 

aTEView := TTEViewCDoCreateViewsCNIL, NIL, 
kViewRsrcID, gZeroVPt)); 

FailNILCaTEView); 


( Set up initial text specs ) 
GetFontNameCaTEV iew.fTextStyle.tsFont, 
fontName); 
WITH gDefaultSpecs, aTEView DO 
BEGIN 
theTextFont := fontName; 
theTextFace := fTextStyle.tsFace; 
theTextSize := fTextStyle.tsSize; 
theTextColor := fTextStyle.tsColor; 
theJustif ication := fJustif ication; 
theBackColor := gRGBWhite; 
END; 
alEView.Free; 


( Until MacApp 2.0 debug and ViewTemplates support REALs 
this is our work around from Calvin Cock’s January ’89 MapApp 
Frameworks article. } 

gFieldToStrRtn :- eMyFieldToString; 


END; 


( 

($1FC qDebug) 
($S ADebug) 
PROCEDURE TPlotApplication. IdentifySof tware; 


BEGIN 

WriteLnC'Plot Source date: 31 Jen 89; Compiled: ’, 
COMPDATE, 76”) COMPTIME); 

INHERITED IdentifySof tware; 

END; 


PROCEDURE TPlotApplication.FieldsC 
PROCEDURE DoToF ieldCfieldName: Str255; 
fieldAddr: Ptr; 
fieldType: INTEGER2); 
OVERRIDE; 
BEGIN 
WITH gDefaultSpecs DO 
BEGIN 
DoToFieldC^ Font’, @theTextFont, bFontName ); 
DoToField(' Face’, @theTextFace, bStyle); 
DoToField(’ Size’, @theTextSize, bInteger); 
END; 


(ooeocooooecooooeooocpobeoooococeocooc oce eec eec eeeexo) 
( TPlotDocument 

(xxxxx ЖЖЖЖ) 
($S AOpen) 


PROCEDURE TPlotDoc.IPlotDocument; 
VAR 
aRect: Rect; 

BEGIN 

IDocument(kFileType, kSignature, 
kUsesDataFork, NOT kUsesRsrcFork, 
NOT kDataQpen, NOT kRsrcOpen); 

füldPlot := NIL; 

END; 


( ) 
($S AOpen) 
FUNCTION TPlotApplication.DoMakeDocument(itsCmdNumber : 
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cmdNumber ): TDocument; 
VAR 
aPlotDocument: TPlotDoc; 
dimensions: Rect; 
BEGIN 
( Allocate and initialize the document) 
NEWCaP lotDocument ); 
Fai lNILCaPlotDocument); 
aPlotDocument . IPlotDocument ; 
DoMakeDocument := aPlotDocument; 
END; 


( ) 
($5 AOpen) 
PROCEDURE TPlotDoc.DoInitialState; OVERRIDE; 
BEGIN 
( when reverting to an old copy of a document we 
need to reset to some reasonable values ) 


fPlotSpecs := gDefaultSpecs; 
fOldPlot := NIL; 
END; 


(----------? 
FUNCTION TPlotDoc.DoMakePStuleCmd(itsStule:PlotSpecsPtr; 
itsCmdNumber :CmdNumber): TPStuleCmd ; 
VAR 


aPStuleCmd:TPStuleCmd; 
aPlotDialog: TPlotDialog; 
BEGIN 
NewCaPStyleCmd); 
FailNILCaPStyleCmd); 
aPlotDialog := fPlotDialog; 
aPStyleCmd.IPStyleCmdCaPlotDialog, itsStyle, itsCmdNumber ); 
DoMakePStyleCmd := aPStyleCmd; 
END; 


( ) 

($5 AOpen} 

PROCEDURE TPlotDoc.DoMakeViews(forPrinting: BOOLEAN); 
VAR 


aWindow: TWindow; 
aPlotDialog: TPlotDialog; 
aPlotView: TPlotView; 
aTEView: TTEView; 
asolutionView: TSolutionView; 
aCluster: TCluster; 
aPr intHandler: TStdPr intHandler ; 
anExtendedText: TExtendedText; 
aRect: Rect; 

BEGIN 


( We want to dynamically call these in 
exisitance. Do a New() call for each object 
type, so the linker doesn’t strip them out. } 

IF gCreateWithTemplates THEN 
BEGIN 
NewCaP lotDialog); 

NewCaPlotView); 
NewCaTEView); 
NewCaSolutionView); 
NewCaCluster ); 
NewCanExtendedlext); 
END; 


~ 


we will now ceate and connect up all the view 
and document variables ) 


aWindow := NewlemplateWindow(kPlotDialog, SELF); 
( bring our plot window into exisitance ) 


aPlotDialog := TPlotDialogCaWindow.F indSubV iewC'DLOG "22; 
FailNILCaPlotDialog); 
(find dialog portions & make certian we have it } 
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fPlotDialog := aPlotDialog; 
( save this awau for late when we need 
to easilu find the dialog ) 


aPlotDialog.fPlotDoc := SELF; 
( and of course we need to cross refer so 
tell the plotdialog who its doc is ) 


IF CfOldPlot © NIL) 

| CGetHandleSizeCHandleCfOldPlot)) > Ø )THEN 

aPlotDialog.fPlotPICT := fOldPlot 

( If the document has an old plot PICT display it ) 
ELSE 

aPlotDialog.GetPlotValues; 

( Use the values from the resource to 

generate the first plot } 


( Find the PlotView and make some 
connections to our PlotDocument ) 

aPlotView := TPlotViewCaWindow.F indSubView( ‘plot’)); 
FailNILCaPlotView); 
aPlotView.fPlotDoc := SELF; 
aPlotDialog.fPlotView := aPlotView; 
aPlotDialog.fPlotPICT := NIL; 
aPlotDialog.fPlotSize aPlotView.fSize; 


( Find the SolutionView and make some 
connections to our PlotDocument ) 
aSolutionView := TSolutionViewCaWindow.F indSubView( ‘qslv’)); 
Fai INILCaSolutionView); 
asolutionView.fPlotDoc := SELF; 
aPlotDialog.fSolutionView := aSolutionView; 


( while we are at it, retrieve the rectangle 
Size we will use to display in } 
SetRectCaRect,0,0,aSolutionView.fSize.h, 
asolutionView.fSize.v); 
asolutionView.fSolveRect := aRect; 


( we want to limit the minimum size this 
window can be so.. use the size of our 

clusters to determine the minimum) 
aCluster :-TClusterCaWindow.F indSubV iewC'Ccof ^2); 
aWindow.fResizeLimits.top:- aCluster.fSize.v*2; 
aWindow.fResizeLimits.left:-aCluster.fSize.h*3; 
aCluster:= TClusterCaWindow.F indSubV iewC'Cdsp / 2); 
aWindow.fResizeLimits.top := aWindow.fResizeLimits. top 

+ eCluster .fSize.v; 


NEWCaPr intHandler ); 

FailNILCaPrintHandler); 

aPrintHandler .IStdPrintHandler(SELF, ( its document ) 
aPlotDialog,  ( its view ) 

( does not have square dots ) 

FALSE, ( horzontal page size is fixed ) 
TRUE, ( vertical page size is variable 
(could be set to true on 
non-style TE systems) ) 


FALSE); 
aPrintHandler.fMinimalMargins := FALSE; 
END; 

) 


( 
($S ASelCommand) 


FUNCTION TPlotDoc .DoMenuCommand( 


aCmdNumber: CmdNumber): TCommand; OVERRIDE; 


VAR 
aName: 917255; 
menu: INTEGER; 
item: INTEGER; 
newStyle: PlotSpecs; 


(=== ===) 
PROCEDURE DoSizeChange(base: CmdNumber ); 
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BEGIN 
newStyle.theTextSize := aCmdNumber - base; 
DoMenuCommand := DoMakePStyleCmd( 

@newStyle, cSizeChange); 
END; 


(—________———_—__} 

PROCEDURE DoRelSizeChangeCamount: INTEGER); 
BEGIN 
WITH newStyle DO 


theTextSize := theTextSize + amount; 
DoMenuCommand := DoMakePStyleCmd(@newStyle, cSizeChange); 
END; 


(——-VWÜ 

PROCEDURE DoFontChange; 
BEGIN 
Getltem(GetMHandle(menu), item,newStule.theTextFont); 
GetFNum(aName, newStule.theFontNum); 


DoMenuCommand := DoMakePStuleCmd(@newStule, cFontChange); 


END; 


оа--:) 
PROCEDURE DoColTextChange; 


VAR 
aColor: RGBColor; 
BEGIN 
aColor := fPlotSpecs.theTextColor; 


IF GetColor(Point($00400040), 
GetPromptCkColTextPrompt2^, 
aColor, newStyle.theTextColor) THEN 
DoMenuCommand := DoMakePStyleCmd( 
@newStule, cColorText); 
END; 


(—_______—_——__) 
PROCEDURE DoColGraphChange; 
VAR 


aColor: 

BEGIN 

aColor := fPlotSpecs.theGraphColor; 

IF GetColor(Point($00400040), 
GetPrompt(kColGraphPrompt)*, aColor, 
newStyle.theGraphColor) THEN 

DoMenuCommand := DoMakePStyleCmd(@newStyle, cCol- 
orGraph); 

END; 


RGBColor; 


(——— qT —W An, 
PROCEDURE DoColAxisChange; 


VAR 
aColor: RGBColor; 
BEGIN 
aColor := fPlotSpecs. theAxisColor; 


IF GetColor(Point($00400040), 
GetPrompt(kColAxisPrompt)*, aColor, 
newStyle.theAxisColor) THEN 

DoMenuCommand := DoMakePStyleCmd( 
@newStyle, cColorAxis); 

END; 


Se) 
PROCEDURE DoColBackChange; 


VAR 
aColor : RGBColor; 
BEGIN 
aColor := fPlotSpecs. theBackColor; 


IF GetColorCPoint($00400040), 
GetPrompt(kColBackPrompt)*, aColor, 
newStyle.theBackColor) THEN 
BEGIN 
DoMenuCommand := DoMakePStyleCmd(C 

6newStyle, cColorBackGround); 
END; 


2 


2 
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END; cSizeShr ink: 
DoRelSizeChangeC - kRelSizeAmount); 
(--------”?) cJustLef t . .cJustRight: 
PROCEDURE DoJustChange; 


DoJustChange; 
VAR cPlainText: 
newJust: INTEGER; DoPlainChange; 
BEGIN cBold. .cExtend: 
CASE aCmdNumber OF DoStyleChange; 
cJustLef t : cColorText: 
newJust := teJustLeft; DoColTextChange; 
cJustCenter : cColorGraph: 
newJust := teJustCenter; DoColGraphChange; 
cJustRight : cColorAxis: 
newJust := teJustRight; DoColAxisChange; 
END; cColorBackground: 
newStyle. theJustification := newJust; DoCo 1BackChange ; 


DoMenuCommand := DoMakePStyleCmd(@newStyle, aCmdNumber ); 
END; OTHERWISE 
DoMenuCommand := INHERITED 


(———cr x q — . QÜ)ə)U DoMenuCommand(aCmdNumber ); 
PROCEDURE DoP lainChange; END; 
BEGIN END; 
newStyle.theTextFace := (1; 
DoMenuCommand := DoMakePStyleCmd(@newStyle, cStyleChange); (——V,YÜ 
END; ($S ARes) 
( RE TPlotDoc.DoSetupMenus; OVERRIDE; 
PROCEDURE DoStyleChange; hasColor : BOOLEAN; 
VAR hasStyle: BOOLEAN; 
newFace : Style; checkPlain: BOOLEAN; 
BEGIN checkS ize: BOOLEAN; 
WITH newStyle DO checkFont : BOOLEAN; 
BEGIN 


specChange: BOOLEAN; 


CASE aCmdNumber OF just: INTEGER; 
cBold: item: INTEGER; 
newFace := [bold]; fnt: INTEGER; 
cltalic: C: INTEGER; 
newFace := [italic]; eMode: INTEGER; 
cUnder line: aFace: Style; 
newFace := [underline]; aMenuHandle: ` MenuHandle; 
cOutline: aName: Str255; 
newFace := [outline]; eStyle: TextStyle; 
cShadow : theFont : INTEGER; 
newFace := [shadow]; astr255: Str255; 
cCondense : BEGIN 
newFace := [condense]; INHERITED DoSetupMenus; 
cExtend: 
newFace := [extend]; hasColor := gConfiguration.hasColorQD; 
END; hasStyle := gConfiguration.hasStyleTextEdit; 


IF newFace * theTextFace = newFace THEN 
theTextFace := theTextFace - newFace aStr255 := fPlotSpecs.theTextFont; 
ELSE GetFNumCaStr255, aStyle.tsFont); 
theTextFace := theTextFace + newFace; WITH aStyle, fPlotSpecs DO 
; BEGIN 


DoMenuCommand := DoMakePStuleCmd( tsFace := theTextFace; 
énewStyle, cStyleChange?; tsSize := theTextSize; 
END; tsColor := theTextColor; 
END; 
0офа-------) checkPlain := aStyle.tsFace = []; 
BEGIN ( DoMenuCommand ) checkFont := TRUE; 


DoMenuCommand := gNoChanges; 
aMenuHandle := GetMHandle(mFont); 
newStyle := fPlotSPecs; 
GetFontNameCaStyle.tsFont, aName); 
( Get real font number in case tsFont is ) 
GetFNumCaName, theFont); 
( .the system or application font. ) 
FOR item := 1 TO CountMItemsCeMenuHandle?) DO 
BEG 


CndToMenuItemCaCmdNumber, menu, item); 


IF menu = mFont THEN 
DoFontChange 


ELSE 
CASE aCmdNumber OF 
cSizeMin. .cSizeMax: 
DoS izeChange(cSizeBase ); 
cSizeGrow: 
DoRe 1SizeChange(kRe1SizeAmount ); 


( There can be more than 31 menu entries 
with scrolling menus, but trying to enable 
an item with number > 31 is bad news. 

If the menu itself is enabled Cwhich it 
will be in MacApp if any of the first 31 
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items is enabled), then the extras 

will alwaus be enabled. ) 

IF item <= 31 THEN 
EnableItemCaMenuHandle, item); 

IF checkFont THEN 
BEGIN 
GetItemCaMenuHandle, item, aName); 
GetFNumCaName, fnt); 
CheckItemCaMenuHandle, item, fnt = theFont); 
END; 

END; 


just := fPlotSpecs.theuust if ication; 

( Enable justification related menu items ) 
EnableCheckCcJustLeft, TRUE, (just = teJustLef t2); 
EnableCheckCcJustCenter, TRUE, (just = teJustCenter)); 
EnableCheckCcJustRight, TRUE, (just = teJustRight)); 


($1FC NOT qNeedsHiererchialMenus) 

IF gConfiguration.hasHierarchicalMenus THEN 

($ENDC) 
BEGIN 
EnebleCcStyle, TRUE); 
EnableCcSize, TRUE); 
EnableCcFont, TRUE); 
EnableCcColor, hasColor); 
END; 


( Enable sub-menus ) 


aFace := eStyle.tsFace; 
EnableCheck(cPlainText, TRUE, checkPlain); 

( Enable normal Style menu items ) 
EnableCheck(cBold, TRUE, bold IN aFace); 
EnableCheck(cItalic, TRUE, italic IN aFace); 
EnableCheck(cUnderline, TRUE, underline IN аҒасе); 
EnableCheck(cOutline, TRUE, outline IN aFace); 
EnableCheck(cShadow, TRUE, shadow IN aFace); 
EnableCheck(cCondense, TRUE,condense IN аҒасе); 
EnableCheck(cExtend, TRUE, extend IN aFace); 


FOR c := cSizeMin TO cSizeMax DO 
BEGIN 
IF hasStyle THEN 
checkSize := FALSE 
ELSE 
checkSize := (c - cSizeBase) = aStyle.tsSize; 
EnableCheck(c, TRUE, checkSize); 


IF «NOT hasStyle) | 
( If the record isn't styled, or ) 
RealFontCaStyle.tsFont,c-cSizeBase)) 
( the size is a real one ) 
THEN aFace := [outline] 
( .then we outline it ) 
ELSE 


eFace := []; 
SetStyleCc, aFace); 
END; 


EnableCcSizeGrow, TRUE); 
EnableCcSizeShrink, TRUE); 


EnableCcColorText, hasColor); 
EnableCcColorBackground, hasColor); 
EnableCcColorGraph, hasColor); 
EnebleCcColorAxis, hasColor); 


END; 


( 
($5 AwriteFile) 
PROCEDURE TPlotDoc.DoNeedDiskSpace( 
VAR dataForkBytes, rsrcForkBytes: LONGINT); 
VAR 
r: Rect; 
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BEGIN 
( In other МасАрр Samples we would normally get 
the Print record space requirements by doing: 


INHERITED DoNeedDiskSpaceCdataForkBytes, rsrcForkBytes); 


BUT seeing as we are trying to imitate a 
MacDraw File we will just do our size 
calculation 


dataForkBytes := kHeaderSize ( for std MacDraw Header ) 
+ GetHandleSizeCHandle(fPlotDialog.fPlotPICT)); 


( For now we will write only the PICT Handle in 
the future we might want to write the 
PlotSpecs and other parameters to the resource 
fork of the file } 

rsrcForkBytes := 0; 

END; 


( 
($S AReadF ile) 


PROCEDURE TPlotDoc.DoReadCaRefNum: INTEGER; rsrcExists, 
forPrinting: BOOLEAN); 
VAR 
fi: FaillInfo; 
aPICTSize: LONGINT; 
aPICTHandle:Handle; 


PROCEDURE SkipDocHeader Info; 
BEGIN 

( skip the dummy header ) 

END; 


PROCEDURE HdlReadFailureCerror: OSErr; message: LONGINT); 
BEGIN 


{ We ran into trouble reading the data for 
now do nothing) 
END; 


BEGIN 
CatchFailures(fi, HdlReadFailure); 


( Normally, we would ask our ancestors to read 
in their data by: 
INHERITED DoRead(CaRefNum, rsrcExists, forPrinting); 
but we are imitating a MacDraw Doc and have 
to behave like one 


Sk ipDocHeader Info; 


IF fOldPlot © NIL THEN 
DisposHandleCHandleCfOldPlot)); 


FailOSErrCGetEOF CaRef Num, aPICTSize)); 
aPICTSize := aPICTSize - kHeaderSize; 
aPICTHandle := NewHandleCaPICTSize); 


HLockCaPICTHandle); 
ReadBytesCaRefNum, aPICTSize, aPICTHandle^); 
HUnLockCaP ICTHandle); 


füldPlot := PicHandleCaPICTHandle); 


Success(f i); 


a 


( 
($5 AWriteFile) 
PROCEDURE TPlotDoc.DoWriteCaRefNum: INTEGER; makingCopy: 


Ға1105Егг( SetFPosCaRefNum, fsFromStart, kHeaderSize)); 
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BOOLEAN); 
PROCEDURE WriteHeaderInfo; 


VAR 
aPtr: Ptr; 

BEGIN 
aPtr := NewPtrC lear (kHeaderSize); 
FailNilCaPtr); 
WriteBytesCaRefNum, kHeaderSize, aPtr); 
DisposPtrCaPtr); 

END; 

PROCEDURE WritePlotInfo; 
VAR 


ePICTHandle : Handle; 

ePICTSize : LONGINT; 
BEGIN 

aPICTHandle := Handle(fPlotDialog.fPlotPICT); 
aPICTSize := GetHendleSizeCaPICTHandle?; 


HLockCaPICTHandle); 
WriteBytesCeRefNum, aPICTSize, aPICTHandle ); 
HUnLock CaP ICTHandle?); 

END; 


BEGIN 
Wr i teHeader Info; 
WritePlotInfo 
END; 


( ) 
($S ARes) 
PROCEDURE TPlotDoc.SolveQuadratic; 
VAR 
8,b,c,check : real; 


FUNCTION PositiveCalc(a, b, check:real):real; 


PositiveCalc := (-b + sqrt(check)) / (2 * a); 
END; 


FUNCTION NegativeCalc(a, b, check:real):real; 
BEGIN 
NegativeCalc := (-b - sqrt(check)) / (2 * a); 
END; 


BEGIN 
8 :* faParam; 
fbParam; 


fcParam; 


b: 
с 


check := (b * b) - (4 * a * с), 


IF check = 0 THEN 
( we have a double root (same place twice) } 
BEGIN 
fRootTupe := SingleSolution; 
fistRoot := PositiveCalc(a, b, check); 
f2ndRoot := f 1stRoot; 
END 


ELSE IF check » 2 THEN 
( we have a pair of “real? x axis crossings ) 
BEGIN 
fRootType :- RealRoots; 


fistRoot := PositiveCalcCa, b, check); 
f2ndRoot := NegativeCalcCa, b, check); 
END 


ELSE IF check < 0 THEN 
( roots are represented by complex number ) 


BEGIN 
fRootType := ComplexRoot; 
check := -check; 
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fistRoot := PositiveCalcCa, b, check); 
f2ndRoot := NegativeCalc(a, b, check); 
END; 
END; 
(oo 


($S ANonRes) 
PROCEDURE TPlotDoc.ChangeBackColor(newColor: RGBColor); 
VAR 


oldPort: GrafPtr; 
itsWindow: TWindow; 
BEGIN 


itsWindow := TViewCfPlotDialog2.GetWindow; 
IF itsWindow € NIL THEN 
BEGIN 
GetPortColdPort); 
SetPortCitsWindow.fWMgrWindow2; 
RGBBackColor(newColor); 
itsWindow.ForceRedraw; 
SetPortColdPort); 
END; 
END; 


( 
($IFC qDebug) 
($S Fields) 
PROCEDURE TPlotDoc.Fields@ROCEDURE DoToF ieldCf ieldName: 
$tr255; fieldAddr: Ptr; fieldType: INTEGER)); OVERRIDE; 
VAR 
aStr : DecStr; 
form : DecForm; 
aReal: Real; 
BEGIN 
form.style := FloatDecimal; 
form.digits := 6; 


DoToFieldC'TPlotDoc'/, NIL, bClass); 
aReal := faParam; 
Num2Str (form, aReal, aStr); 
DoToField(‘faParam’, @aStr, bString); 


aReal := fbParam; 
Num2Str (form, aReal, aStr); 
DoToField(’fbParam’, @aStr, bString); 


aReal := fcParam; 
Num2Str (form, aReal,astr); 
DoToField(‘fcParam’, @aStr, bString); 


aReal := fstepParam; 
Num2Str (form, aReal, aStr); 
DoToField(‘fstepParam’, @aStr, bString); 
DoToField(‘fxParam’, @fxParam, bInteger); 
DoToField(‘fyParam’, @fyParam, bInteger); 


DoToField(’ Font’, efPlotSpecs.theTextFont, bFontName); 
DoToField(’ Face’, efPlotSpecs.theTextFace, bStyle); 
DoToField(’ Size’, @fPlotSpecs.theTextSize, bInteger); 


INHERITED FieldsCDoToF ield); 
END; 
($ENOC) 


(REMAKE KER хх Ххх AA KER EEE EE EE) 
( TPlotDialog 


(ЖЖЖЖ KEKE A AKER EAE EEK ккк) 


(5) 
PROCEDURE TPlotDialog.DismissDialog( 
dismisser: IDTupe; flashDismisser: BOOLEAN); 
OVERRIDE; 
BEGIN 
INHERITED DismissDialog(dismisser, flashDismisser ); 
END; 
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(—— W 
FUNCTION TPlotDialog.DoKeyCommand(ch: CHAR; 
eKeyCode: INTEGER; VARinfo: EventInfo): TCommand; 
OVERRIDE; 
BEGIN 
( If Enter is pressed, assume we have new 
parameters and a new plot to create. ) 
IF (ch = chEnter) THEN 
BEGIN 
(we have everything we need, lets DOIT!) 
PlotNDrawPICT; 
(We did all the work no reason to 
generate a command) 
DoKeyCommand := gNoChanges; END 
ELSE 
DoKeyCommand := INHERITED 
DoKeyCommand(ch, aKeyCode, info); 
END; 


(1.---------) 
FUNCTION TPlotDialog.DoMenuCommand( 
aCmdNumber: CmdNumber): TCommand; OVERRIDE; 
BEGIN 


( Plot Menu Command was chosen so create plot. ) 

IF (aCmdNumber = cPlotIt) THEN 
BEGIN 
PlotNDrawPICT; ( we have everything, lets DOIT! ) 
DoMenuCommand := gNoChanges; 

( We did all the work no reason to generate a command) 

END 

ELSE 


END; 


2--------:-:-) 
PROCEDURE TPlotDialog.DoSetupMenus; OVERRIDE; 
BEGIN 


EnableCcPlotIt, TRUE); 
INHERITED DoSetupMenus; 
END; 


02-----------”) 
PROCEDURE TPlotDialog.DrawCarea: Rect); OVERRIDE; 
VAR 


plotRect : Rect; 
dontCare : BOOLEAN; 
BEGIN 
dontCare := fPlotView.Focus; 
( set the world up to focus all drawing 
in the PlotView } 


fPlotView.GetQDFrame(plotRect); 
{ the design says we draw into the 
available frame ) 


DrewPictureCfPlotPICT, plotRect); 
( Draw the PICT in the PlotView } 


dontCare := SELF .Focus; 
( shift the focus back to us } 
END; 


(——_______—___) 
PROCEDURE TPlotDialog.EachSubV iew PROCEDURE 
DoToSubViewCtheSubView: TView)); 
BEGIN 
( We do not want all of our clever 
dialog elements printing so lets 
Skip them when printing } 
IF NOT gPrinting THEN 
INHERITED EachSubV iewCDoToSubV iew); 
END; 


SSS SS) 
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DoMenuCommand := INHERITED DoMenuCommand(aCmdNumber ) : 


PROCEDURE TPlotDialog.PlotNDrawPICT; 
VAR 


plotRect : Rect; 
SolveRect : Rect; 
saveClip : RgnHandle; 
pstate : PenState; 
dontCare : BOOLEAN; 


aFontNum : INTEGER; 
BEGIN 
GetPlotValues; 


( get current values from the view ) 
fPlotDoc.SolveQuadratic; 
( for the parameters retrieved, setup 
the solution values ) 


IF fPlotPICT © NIL THEN 
KillPictureCfPlotPICT); 


dontCare := fPlotView.Focus; 
fPlotView.GetQDExtent(plotRect); 

( change MacApp’s focus to the plotview 
to properly get our plot rect) 

dontCare := SELF .Focus; 

( and of course lets set FOCUS back to us. 
The above process of setting up plotRect 
might have been better handleed by 
declaring an fRect in plotview 
end having the resize method of plotview 
keep it up to date) 


fPlotPICT := OpenPicture(plotRect); 
saveClip := NewRgn; 
FailNILCSaveClip); 
GetClip(SaveClip); 
GetPenState(pstate); 


( setup the font info for our plot ) 
($Push) ($H-} 


GetFNum(fPlotDoc. fPlotSpecs. theTextFont, aFontNum); 


($H+) 
TextFontCaFontNum); 
TextSizeCfPlotDoc.fPlotSpecs.theTextSize); 
TextFace(fPlotDoc.fPlotSpecs. theTextFace); 
( we also have: theTextColor, 
theJustification, theBackColor 
that we might want to do something with 
in the future } 
TextMode(srcOr); 


(Begin MacDraw Document РІСТ) 
PicComment(picDwgBeg, 0, NIL); 
PicComment(picGrpBeg, 0, NIL); 


fPlotView.AddToPict(plotRect); 

SolveRect := fSolutionView.fSolveRect; 
( get our plot rect, we know that this 
is a fixed rect) 


offsetRectCsolveRect,4 (border), 


plotRect .Bottom-CsolveRect .Bottomt4 (border) )): 


( slide the textbox on down to the 
bottom of the view area this assumes 
that the solution textbox is smaller 
then the plotRect) 


fSolutionView.AddToPict(solveRect); 


PicComment(PicGrpEnd, Ø, NIL); 
PicComment(picDwgEnd, 0, NIL); 
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ClosePicture; 


SetPenState(pstate); 
SetClip(saveClip); 


DisposeRgn(saveClip); 


ForceRedraw; 
( make the dialog rect invalid ) 
ЕМО; 


(————ə > D" > — —— o—əsÉ) 
PROCEDURE TPlotDialog.GetPlotValues; 
BEGIN 


fPlotDoc.faParam := 
TExtendedTextCF indSubView( ‘cofA’)).GetValue; 

fPlotDoc.fbParam := 
TExtendedText(F indSubV iewC ‘cofB’)).GetValue; 

fPlotDoc.fcParam :- 
TExtendedText(F indSubV iew( ‘cofC’)).GetValue; 


fPlotDoc.fstepParam := 
TExtendedText(F indSubV iew( ‘step’)).GetValue; 
fPlotDoc.fxParam := 
TNumber Text СЕ indSubV iew( ‘xAxs’)).GetValue; 
fPlotDoc.fyParem := 


TNumber Text СЕ indSubV iew( ‘yAxs’)).GetValue; 


END; 
(---------!) 
PROCEDURE TPlotView.GetQDFrame(VAR frameRect :Rect); 
VAR 
extent: VRect; 
BEGIN 
GetFrameCextent); 


ViewToQDRectCextent, frameRect); 


END; 


SS) 
PROCEDURE TPlotView.AddToPict(picRect :Rect); 


CONST 
AxisLabelIndent = 4; 

TYPE 
Widpt = Point; 
WidPtr = “WidPt; 
WidHdl = “WidPtr; 

VAR 
x, U : Real; 
a,b,c : Real; 
step : Real; 
halfXScale : Real; 
xPictScale : Real; 
yPictScale : Real; 
lestPt : Point; 
thisPt : Point; 
xScale : INTEGER; 
yScale : INTEGER; 
CenterHorz : INTEGER; 
CenterVert : INTEGER; 
PictHorz : INTEGER; 
PictVert : INTEGER; 
leading : INTEGER; 
fInfo : Font Info; 
Width : Widhdl; 
axisLabel : str255; 
newColor : RGBColor; 
oldBack : RGBColor; 
oldFore : RGBColor ; 
drawLine : BOOLEAN; 
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BEGIN 
Width := Widhdl(NewHandle(sizeof (widpt22); 
Width^^.h := 10; 
Width^^.v := 1; 


GetFontInfo(flnfo); 
leading := flnfo.descent 
+ fInfo.ascent + flnfo.leading; 


WITH fPlotDoc DO 
BEGIN 
( retrieve the length of our Axis ) 
xScale := fxParam; 
yScale := fuParam; 


{ retrieve the coeficients } 
a := faParam; 

b := fbParam; 

с := fcParam; 

Step := fStepParam; 

END; 


ClipRect(picRect); 


GetForeColorColdFore); 
GetBackColorColdBack); 


PenNormal; 


(Draw Graph Boundry) 
PicComment(picGrpBeg, 0, NIL); 


newColor := fPlotDoc.fPlotSpecs. theBackColor ; 
RGBBackColor(newColor ); 


PicCommentCSetL ineWidth, 
GetHandleSize(Handle(Width)), HandleCWidth)); 

FillRect(picRect, white); 

FrameRect(picRect); 


(Two Axis) 
newColor := fPlotDoc.fPlotSpecs.theAxisColor; 
RGBForeColor(newColor); 


( find height of our View we will draw into } 
PictHorz := picRect.right - picRect. left; 
PictVert := picRect.bottom - picRect. (ор; 


( find the center coordinates of the view } 
CenterHorz := PictHorz DIV 2; 
CenterVert := PictVert DIV 2; 


PicComment(picGrpBeg, Ø, NIL); 
movetoCO, CenterVert); 
lineC PictHorz, 0); 
movetoCCenterHorz, 0); 
line(@, PictVert); 
PicComment(picGrpEnd, Ø, NIL); 


newColor := fPlotDoc.fPlotSpecs.theGraphColor ; 
RGBForeColor(newColor); 


(Axis Text} 
( Place -X axis label to the lowerleft of 
the axis line } 
movetoCAxisLabellndent, CenterVert + leading); 
NumToS tr ing(-xScale, axisLabe 1); 
DrawStr ingCaxisLabe); 


{ Place +Y axis label to the topleft of the 
axis line } 

NumToStr ing(yScale, axisLabel); 

moveto(CenterHorz - (StringWidthCaxisLabel) 
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+ AxisLabelIndent), leading); drawLine := TRUE; 


DrawStr ingCaxisLabel); moveToCthisPt.h, thisPt.v) 
END 
( Place +X axis label to the lowerright END; 
of the axis line } UNTIL x >= halfXScale; 
NumToStr ing(xScale, axisLabel); 
moveto(PictHorz - (StringWidthCaxisLabe1) PicComment(picGrpEnd, 0, NIL); 
+ AxisLabelIndent), CenterVert + leading); 
DrawStr ingCaxisLabel); RGBForeColor(oldFore); 


RGBBackColor(oldBack >; 
( Place -Y axis label to the lowerleft 


of the axis line } PicComment(PicGrpEnd, 0, NIL); (of select 811 objects) 
NumToS tr ing(-yScale, axisLabe1); 
movetoCCenterHorz - (StringWidthCaxisLabel) END; 


+ AxisLabelIndent), PictVert - leading); 
DrawStr ingCaxisLabel); 


( ) 
PROCEDURE TPlotView.Resize(width, 


(The Plot) height: VCoordinate; invalidate: BOOLEAN); 
( calculate a scale factor for the OVERRIDE; 
PICT’s axis in the view ) BEGIN 
xPictScale := PictHorz / xScale; invalidate := TRUE; 
yPictScale := PictVert / yScale; INHERITED ResizeCwidth, height, invalidate); 
ForceRedraw; 
END; 
( calculate our starting x,y point ) 
halfXScale := xScale / 2; 
x := -halfXScale; ( Adds the text box containing the Quadratic equation solution 
y:=a*®x*¥ xt (b * x) жс; to our PICT. ) 
PROCEDURE TSolutionView.AddToPict(picRect: Rect); 
( Scale it into the PICT’s CONST 
Cand PostScript’s) view space} kistLine = 1; k2ndLine = 2; k3rdLine = 3; 
thisPt.h := k4thLine = 4; k5thLine = 5; 
integer(round(x * xPictScale))+CenterHorz; 
thisPt.v := kLeftJust = 1; 
integer(round(-y * yPictScale))+CenterVert; kIndent = 2; 
TYPE 
( Find where to stop and start drawing. Widpt = Point; 
LOOP until we reach all x values: WidPtr = “WidPt; 
1. Find our first visible line segment WidHd] = ^WidPtr; 
2. Plot until it disappears 
3. Find a suitable end point TTxtPicRec = PACKED RECORD 
tJus : Byte; 
tFlip : Byte; 
WHILE (NOT PtInRect(thisPt, picRect)) tRot : Integer; 
& (x <= halfXscale) DO tLine : Byte; 
BEGIN tCmnt : Byte; 
X := x + step; END; 
yr=a*x*xt+(b* x) ес; VAR 
thisPt.h := TextClipRgn : RgnHandle; 
integer(round(x * xPictScale))+CenterHorz; TxtPicRec : TTxtPicRec; 
thisPt.v := TxtPicPtr : QDPtr; 
integer(round(-y * yPictScale))+CenterVert; TxtPicHd! : QDHandle; 
END; Width : WidHdl; 
moveToCthisPt.h, thisPt.v); clipBox : Rect; 
drawLine := TRUE; boxTop : INTEGER; 
boxLef t : INTEGER; 
PicComment(picGrpBeg, 0, NIL); leading : INTEGER; 
fInfo : FontInfo; 
REPEAT LineNo  : INTEGER; 
X := x + Step; 
y := (ахї x * x) + (b * x) + c; a,b,c : Real; 
thisPt.h := x1,x2 : Real; 
integer(round(x*xPictScale))+CenterHorz; 21,22 : Real; 
thisPt.v := 
integer(round(-u*uPictScale))+CenterVert; newColor : RGBColor; 
IF NOT PtInRect(thisPt, picRect) THEN 
drawLine :- FALSE BEGIN 
ELSE WITH fPlotDoc DO 
BEGIN BEGIN 
IF drawLine THEN ( retrieve the Solution ) 
LineToCthisPt.h, thisPt.v) x1 := f istRoot; 
ELSE x2 := f2ndRoot; 
BEGIN 
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( retrieve the coeficients ) 


a := faParam; 
b := fbParam; 
c := fcParam; 
END; 


Width := Widhdl(NewHandleCsizeof (widpt))); 
Width^^.h := 10; 
Width**.v := 1; 


GetFontInfocf Info); 


leading := fInfo.descent + fInfo.ascent + fInfo. leading; 


PicComment(picGrpBeg, 0, NIL); 


(Box } 
PicComment(picGrpBeg, 0, NIL); 
PicComment(SetLineWidth, 
GetHandleSizeCHandleCWidth)), 
HandleCWidth)); 
fillRect(picRect, white); 
frameRect(picRect); 
PicComment(picGrpEnd, 0, NIL); (of box) 


TextClipRgn := NewRgn; 
FailNil(TextClipRgn); 


GetClipCTextClipRgn?; 
clipBox := picRect; 
ClipRectCclipBox2; 


newColor := fPlotDoc.fPlotSpecs.theTextColor; 
RGBForeColor(newColor); 


(Box Text) 
( setup our Text Comment Handle } 
TxtPicPtr := @TxtPicRec; 
TxtPicHdl := eTxtPicPtr; 
TxtPicRec.tJus := kLeftJust; 
TxtPicRec.tFlip : (no flip) 
TxtPicRec.tRot := 0; (no rotation) 
TxtPicRec.tLine : (1 1/2 spacing) 


"Ü" "f u d 
ко c 
we we 


(put the Comment into our PICT) 
PicComment(TextBegin, sizeof (TTxtPicRec), 


HandleCTxtP icHd122; 


( Add the BOX text to the PICT ) 
boxTop := picRect.top; 
boxLeft:= picRect.Left; 


MoveToCboxLeft + kIndent, 
boxTop + (kistLine * leading)); 


DrawStr ing(CONCAT( ‘y=ax*2 + bx + с”, chr(13))); 


MoveToCboxLeft + kIndent, 
boxTop + (k2ndLine * leading)); 


DrawString(CONCAT( ‘a=’, Real2Str(a, D, ^, b=’ 


Real2Str(b, 1), “, c=’, Real2Str(c, D, chr(13))); 


( The solution text is next } 
MoveToCboxLeft + kIndent, 
boxTop + (k3rdLine * leading)); 
DrawStr ingCCONCAT( 'x1-/, Real2Str(x1,3), 
' , x27! , Real2Str(x2,3), chrC 1322); 


( Display kind of Quadratic we have ) 
MoveToCboxLeft + kIndent, 
boxTop + (k4thLine * leading); 
CASE fPlotDoc.fRootType OF 
RealRoots : 


DrawStr ing(CONCAT( ‘Two Real Roots, x1, x2’, 


chr(13))); 
SingleSolution : 
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DrawStringCCONCATC'Double Root’, сһг(13222; 
ComplexRoot : 

DrawString(CONCATC ‘Two Complex Roots ‘,chr(13))); 
OTHERWISE 


END; 


( Calculate the slope and add the 
string it to the PICT} 
WITH fPlotDoc DO 


MoveToCboxLeft + kIndent, 
boxTop + (k5thLine * leading)); 
DrawString(CONCATC ‘Slope 0 is C', 
Real2Str(z1,1),’,’, Real2Str(z2, 1),’)’, 
сһг(13222; 


( A11 done with our text) 
PicCommentCTextEnd, 0, NIL); 


PicComment(PicGrpEnd, 0, NIL); (of Box & text) 


DisposHandleCHandleCwidth)); 
DisposeRgn(TextClipRgn); 
END; 


----------? 

PROCEDURE TPStuleCmd.Dolt; 
BEGIN 
fPlotDialog.fPlotDoc.fPlotSpecs 
END; 


fNewPlotSPecs; 


[eee] 

PROCEDURE TPStyleCmd.ReDoIt; 
BEGIN 
fPlotDialog.fPlotDoc.fPlotSpecs 
END; 


fNewPlotSPecs; 


—— шышы) 

PROCEDURE TPStyleCmd.UnDoIt; 
BEGIN 
fPlotDialog.fPlotDoc.fPlotSpecs 
END; 


fOldPlotSPecs; 


(===) 
PROCEDURE TPStyleCmd.IPStyleCmdCitsPlotDialog: TPlotDialog; 
itsNewStule: PlotSpecsPtr; itsCmdNumber: CmdNumber ); 
BEGIN 
ICommandCitsCmdNumber, itsPlotDialog.fPlotDoc, 
itsPlotDialog, NIL); 


fPlotDialog := itsPlotDialog; 
fOldPlotSPecs:-fPlotDialog.fPlotDoc.fPlotSpecs; 
fNewPlotSPecs:-itsNewStyle^; 

END; 


END. 


MPlot.p Main Progrem FILE 
(00000000000000000000000000000000000000000000000) 


Program Plot; 
USES 
( 0 МасАрр ) 
UMacApp, 


( 0 Building Blocks } 
UDialog, UPrinting, 


( O Implementation Use ) 
SANE, ToolUtils, Fonts, Resources, 
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Script, PickerIntf, Packages, 


( O the PlotUNIT ) 
UP1ot; 


VAR 
gPlotApplication: TPlotApplication; 
(The application object:) 


( ) 
(THE MAIN PROGRAM) 
BEGIN 
InitUMacApp(8); 


(Initialize the Toolbox, 
making 8 calls to MoreMasters:) 
InitPrinting; 
(Initialize the UPrinting unit:) 


NEWCgPlotApplication); 
{Allocate a new TPlotApplication object:) 


FailNILCgPlotApplication); 
gPlotAppl ication. IPlotAppl icat ionCkF i leType2; 
(Initialize that new object:) 


gPlotApplication.Run; 
(Run the application. 
When it’s done, exit.) 
END. 


PLOT.r-Plot resource FILE 


/* Copyright € 1988-1989 Apple Computer, Inc. 
All rights reserved. */ 

/* Copyright € 1989 Software Architects, Inc. 
All rights reserved. */ 


"if qDebug 

include “Debug.rsrc’; 
епа? 

include “MacApp.rsrc?; 
include “Dialog.rsrc’; 
include "Printing.rsrc^; 


include “Plot” ‘CODE’; 


define kPlotView 10 10 
"gef ine kViewRsrcID 1005 


resource ‘seg!’ (256, purgeable) ( 


“GOpen’; 
“GClose’; 
“GNonRes? ; 
*GSelCommand” 
) 
5 


resource ‘SIZE’ (-1) ( 
dontSaveScreen, 
acceptSuspendResumeEvents, 
enableOptionSwitch, 
canBackground, 
MultiF inderAware, 
backgroundAndForeground, 
dontGetFrontClicks, 
ignoreChildDiedEvents, 
is32BitCompat ible, 
reserved, 
reserved, 
reserved, 
reserved, 
reserved, 
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reserved, 

reserved, 
®if qDebug 

368 х 1024,  /* 222 BALLPARK GUESSES ?????*/ 

320 * 1024 
"else 

(300-32) * 1024, 

(200-32) * 1024 
"endif 


д 


/% 222 BALLPARK GUESSES ?? 


resource ‘DITL’ (201, purgeable) ( 
( 


/* (1) */ 

(160, 182, 180, 262), Button ( enabled, “OK? ); 
/* (2) */ 

(10, 75, 150, 316), StaticText ( disabled, 


*/ 


“This is an implementation of the MacTutor Plotter Program." 


*AnM written ” 
“with MacApp@ € 1985-1989 Apple Computer, Inc.^); 
ad */ (10, 20, 42, 52), Icon ( disabled, 1) 


); 


resource ‘ALRT’ (1000, purgeable) ( 
(44, 48, 130, 358), 
С 


OK, visible, soundi, 
OK, visible, sound], 
OK, visible, soundi, 
OK, visible, sound! 


); 


resource ‘ALRT’ (201, purgeable) ( 
(90, 100, 280, 412), 
201, 
( 
OK, visible, silent; 
OK, visible, silent; 
OK, visible, silent; 
OK, visible, silent 


); 


resource 'cmnu^ (1) ( 


7 
textMenuProc, 
@xTFFFFFFD, 
enabled, 

i ade 


/* [1] */ 


"About Plotter..”, noIcon, noKey, noMark, plain, cAboutApp; 


/* [2] */ 
*-^, noIcon, noKey, noMark, plain, nocommand 


h 


resource 'cmnu^ (2) ( 
tex tMenuProc, 
QxTFFFEEFB, 
enabled, 
“File”, 


"New",  noIcon, “М”, noMark, plain, cNew; 
“Ореп..”, noIcon, “0”, noMark, plain, cOpen; 

тет, nolcon, noKey, noMark, plain, nocommand; 
“Close”, noIcon, noKeu, noMark, plain,cClose; 
“Save”, nolcon, "S^, noMark, plain, cSave; 
“Save As..”, noIcon,noKey,noMark, plain, cSaveAs; 
“Save а Copy In..", 
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nolcon,noKeu,noMark,plain, cSaveCopu; 
*Revert^,noIcon,noKey, noMark,plain, сКеуегі; 
"em noIcon, noKey, noMark, plain, 


nocommand; 
“Page Setup..”, 
noIcon, noKey, noMark, plain, cPageSetup ; 
“Print..”,nolcon,noKey,noMark, plain, cPr int; 
кыш” noIcon, noKey, noMark, plain, nocommand; 
) “Quit”, nolcon, *Q^, noMark, plain, cQuit 
); 


resource 'cmnu^ (3) ( 
3, 
textMenuProc, 
OxTFFFFFBD, 
enabled, 
“Edit”, 


“Undo”, nolcon, “Z?,noMark, plain, cUndo; 
*-^  molcon, noKeu, noMark, plain, nocommand; 
“Cut”, noIcon, ^X^, noMark, plain, cCut; 
*Copy^,noIcon, “С”, noMark, plain, cCopy; 
“Paste”, 

nolcon, “V”, noMark, plain, cPeste; 
“Clear”, 

nolcon, поКеу, noMark, plain,cClear; 
*-^, nolcon, noKey, поМагк, plain, nocommand; 
“Show Clipboard’, 

noIcon, поКеу, noMark, plain, cShowClipboard 


); 


/* Hierarchical menu with Style, Size & Font submenus */ 
resource ‘cmnu’ (7) ( 

1, 

textMenuProc, 

allEnabled, 

enabled, 

“MacAppP lot”, 


“Plot”, nolcon, noKey, noMark, plain, 1401; 
75, nolcon, noKeu, поМагк, plain, nocommand; 
“Style”, nolcon, “\0х1В*, “\0х08*, plain, 2401; 
“Size”, nolcon, “\@х 18“, *N0x09?, plain, 2402; 
"Font", noIcon, "MOx1B^, *AV@x@A?, plain, 2403; 
E noIcon, “\®x1B%, “\@х@В”, plain, 2404 

); 


/* Hierarchical Stule Sub-menu */ 
resource ‘cmnu’ (8) ( 
8 


) 

textMenuProc, 

allEnabled, 

enabled, 

“Style”, 
"Plain Text^,noIcon, “P”, поМагк, plain, 2001; 
“Bold”, nolcon, “В”, noMark, bold, 2002; 
“Italic”, nolcon, “I”, поМагк, italic, 
2003; 
“Underline”, noIcon, “U”, noMark, underline, 2004; 
“Outline”, nolcon, “0”, поМагк, outline, 2005; 
“Shadow”, noIcon, *5*, поМагк, shadow, 2006; 
“Condensed”, nolcon, noKey, noMark, condense, 2087; 
"Extended^,noIcon, поКеу, noMark, extend, 2008, 
A=? noIcon, поКеу, noMark, plain, nocommand; 


"Left justified” noIcon, noKey, noMark plain, 2201; 
“Center justified”, noIcon,noKey, noMark, plain, 2202; 
"Right justified”,noIcon, noKey,noMark,plain, 2203 
) 


); 
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/* Hierarchical Size Sub-menu */ 
resource 'cmnu^ (9) ( 


9, 

textMenuProc, 

AllEnabled, 

enab led, 

"Size", 
* 9 Point’, noIcon, noKey, noMark, plain, 2109; 
“10 Point’, noIcon, noKey, noMark, plain, 2110; 
“12 Point’, noIcon, поКеу, noMark, plain, 2112; 
“14 Point’, noIcon, поКеу, noMark, plain, 1114; 
“18 Point’, noIcon, поКеу, noMark, plain, 1118; 
“24 Point’, noIcon, noKey, noMark, plain, 1124; 


*-^ по1соп, noKey, noMark, plain, nocommand; 
“Grow selection”, noIcon, 1”, поМагк, plain, 1198; 
"Shrink selection’, nolcon, “[*,noMark,plain, 1199 


) 
); 


/* Font menu for hierarchical or non-hierarchical sustem */ 
resource ‘MENU’ (10) ( 

10, 

textMenuProc, 

&allEnabled, 

enabled, 

*Font^, 

() 
); 


resource ‘cmnu’ (11) ( 
11, 
textMenuProc, 
allEnabled, 
enabled, 
“Color”, 


“Set Graph Color..”, nolcon, noKeu, noMark, plain, 2503; 
“Set Axis Color.^, nolcon, noKeu, noMark, plain, 2504; 
“Set Text Color.^, nolcon, noKeu, noMark, plain, 2501; 
“Set Background Color..", noIcon, noKey, noMark, plain, 2502 


); 


resource ‘cmnu’ (128) ( 
128, 
textMenuProc, 
allEnabled, 
enabled, 
“Buzzwords”, 


“Style Change”, 
nolcon, noKey, noMark, plain, cStyleChange; 
“Size Change”, 
nolcon, noKey, noMark, plain, 2100; 
“Justification Change”, 
nolcon, noKey, noMark, plain, 2200; 
“Font Change”, 
nolcon, noKey, noMark, plain, 2300; 
“Color Change", 
noIcon, noKey, noMark, plain, 2500; 
“Page Setup Change”, 
noIcon, noKey, noMark, plain, 
cChangePr interStyle 
); 


/* Displayed menus on a non-hierarchical system */ 
resource ‘MBAR’ (128) ( 
(1; 2; 3; 8; 9; 10; 11) 
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/* Displayed menus on an hierarchical sustem */ 
resource ‘MBAR’ (131) ( 
(1; 2; 3; 7) 


; 
/* Hierarchial Sub-Menus */ 
resource 2. (130) { 
(8; 9; 10; 11) 


шайы ‘STR®’ (1001, purgeable) ( 


“Select а new text color..", 
“Select background color... 2 
“Select graph line color..^ 
“Select axis color..^ 


» 


/* & resource for picking up default text, 
graph and color info */ 
resource ‘view’ (kViewRsrcID, purgeable) (( 
root, 'TEVW^, (0,0), ( 116, 1020 ), 
sizeVar iable, S izePage, shown, enab led, 
TEView ( "TTEView", 
withStyle, autoWrap, acceptChanges, 
dontFreeText, cTyping, unlimited, 
( 8, 10, 0, 10 ), 
justLeft, plain, 9, (0, 0, 0), "Geneva" ) 


4 


PLOT.VE.r-Plot View resource FILE 
resource ‘view’ (1010, purgeable) ( 


root, ‘WIND’, 

(50, 40), 

(318, 380), sizeVariable, sizeVariable, 

notShown, enabled, 

Window ( 
“TWindow”, 
zoonDocProc ,goAwayBox,resizable, 
modeless, ignoreF irstClick, 
dontFreeOnC losing, disposeOnFree, 
closesDocument, OpenWithDocument, 
AdaptToScreen, Stagger, ForceOnScreen, 
dontCenter, “соҒА”, 
“Plot «0»^ 


), 


‘WIND’, ‘DLOG’, 
(8, 0), (240, 294), 


sizeSuperView, sizeSuperView, shown, disabled, 


DialogView ( 
^TPlotDialog", 
noID, 
noID 


4 


"DLOG^, “соғ”, 


(2, 5), (90, 96), sizeFixed, sizeFixed, shown, disabled, 


Cluster ( 
“TCluster”, 
000, (1, 1),sizeable,notDimmed, notHilited, 
doesnt isniss, (0, 0, 0, 0), 
plain, 12, (0x9, 0x0 , x0). 
“Helvetica”, 
“Coefficients” 


), 


'Ccof^, 'cofA', 


(15, 36), (20, 44), sizeFixed, sizeFixed, shown, enabled 


ExtendedText ( 
"TExtendedText^, 


001101, (1, 1), s izeable,notDimned,notHi1 ited, 
= ——'É—— — P 
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2 


doesntDismiss,(2, 2, 2, 2), 
plain, 0, (0x0, 0х0 0x8), 


justLeft, ”1" unlimited, 
05 11111000000000000000002 100000000 , 
- 19000, 19000,2, "1.0" 


“СсоҒ”, ‘cofB’, 
(38, 36), (20, 44), sizeFixed, sizeFixed, shown, 
ExtendedText ( 
*TExtendedText^, 
061101, (1, 1), sizeable, оне, notHilited, 
doesntDismiss, (2, 2, 2, 
plain, 0, (0x0, 0х0 0x8), 


justLeft, ^5" unlimited, 
0 11110000000000000000000 100000000, 
- 10000, 10000,2, "5.0" 


'Ccof^, ‘cofC’, 
(62, 36), 
(20, 44), sizeFixed, sizeFixed, shown, enabled, 
ExtendedText ( 
*TExtendedText^, 
001101, (1, 1), sizeable, notDimmed,notHilited, 
doesntDismiss, (2, 2, 2, 2), 
plain, 0, (0x0, 0х0 0х0), 


justLeft, ^2" unlimited, 
дь 11110000000000000000000 100000000, 
- 10000, 10000,2, "2.0" 

), 


'Ccof^, 'VW13/, 
(15, 10), 
(20, 26), sizeFixed, sizeFixed, shown, disabled, 
StaticText ( 
*TSteticText^, 
00111, (1, 1), notSizeable, notDimmed, 
notHilited, doesntDismiss, (0, 0, 0, 0), 
plain, 0, (0x8, 0x0 , 0x0) , 


justRight, 
“a = * 


), 


"Ccof^, 'VW14', 
(38, 10), 
(20, 26), sizeFixed, sizeFixed, shown, disabled, 
StaticText ( 
*TStaticText"^, 
06111, (1, 1), notSizeable, notDimmed, 
notHilited, doesntDismiss, (0, 0, 0, 8), 
plain, 0, (0х0, 0х0,0х0), 


justRight, 
“b z^ 
), 


'Ccof^, 'VW15', 
(62, 10), 
(20, 26), sizeFixed, sizeFixed, shown, disabled, 
StaticText ( 
*TStaticText^, 
0b111,(1, 1), notSizeable, notDimmed, 
notHilited, doesntDisniss, (0, 0, 0, 0), 
plain, 0, (6x0, 0х0,0х0), 


justRight, 
"co z^ 


enabled, 
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“01060” 
(95, 5), 
(139, 96), sizeFixed, sizeFixed, shown, disabled, 
Cluster ( 

*TCluster^, 

060, (1, 1), sizeable,notDimmed, 

notHilited, doesntDismiss, (0, 8, Ø, 0), 

plain, 12, (0х0, 0х0,0х0), 

“Helvetica” ; 

“Display” 


‘Cdsp’, 


), 


‘Cdsp’, ‘step’, 
(26, 36), 
(20, 40), sizeFixed, sizeFixed, shown, 
ExtendedText { 
“TExtendedText”, 
061111, (1, 1), sizeable, ерме, 
notHilited, doesntDismiss, (2, 2, 2, 2), 
plain, 0, (0x0, 0х0,0х0), 


enabled, 


justRight, * |" unlimited, 


0b11110000000000000000000 100000000, 0, 10, 2, “0.25” 


), 


‘Cdsp’, ‘xAxs’, 
(66, 17), 
(20, 60), sizeFixed, sizeFixed, 
shown, enabled, 
NumberText ( 
*TNunberText^, 
061111, (1, 1),sizeable,notDimned, 
notHilited, doesntDisniss, (2, 2, 2, 2), 
plain, 0, (0х0, 0х0,0х0), 


justRight, 910" unlimited, 
до 11110000000000000000000 100000000, 10, 1, 1000 


), 


'Cdsp', 
(106, 17), 
(20, 60), sizeFixed, sizeFixed, shown, enabled, 
Number Text ( 

“TNumber Text”, 

061111, (1, 1}, sizeable, о, 

notHilited, doesntDismiss, (2, 2, 2, 2}, 

plain, 0, (9х0, 0х0 , 0x0) , 


“Ах”, 


justRight, ^20" unlimited, 
0b 11110000000000000000000 100000000 , 20, 


‘Cdsp’, ‘VW17’, 
(13, 31), 
(12, 40), sizeFixed, sizeF ixed, 


1, 1000 


shown, disabled, 
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StaticText ( 
#TStaticText”, 
@b8, (1, 1), notSizeable, notDimmed, 
notHilited, doesntDismiss, (0, 0, 
plain,9, (0x0, 0х0 , 0x0) , 
"Helvetica", 
justCenter, 
“step” 


), 


'Cdsp', 
(54, 17), 
(12, 60), sizeFixed, sizeFixed, shown, disabled, 
StaticText ( 

*TStaticText^, 

00, (1, 1), notSizeable, поо ed 

notHilited, doesntDismiss, (0, 0, 0, 0), 

plain,9, (0x0, 0x0 , xB), 

"Helvetica", 

justCenter, 
“X AXIS" 


'Cdsp', 
(93, 17), 
(12, 60), sizeFixed, sizeFixed, shown, disabled, 
StaticText ( 

"TStaticText^, 

000, (1, 1), notSizeable, рш, 

notHilited, doesntDismiss, (0, 0, 0, 0), 

plain,9, (0x6, 0x0 ,0x0) , 

"Helvetica", 

justCenter, 
) *Y АХІ5” 


‘DLOG’, ‘sclr’, 
(0, 104), (225, 175), 
sizeRelSuperView, sizeRelSuperView, shown, 

Scroller ( 

“TScroller’, 

Ver tScrol1Bar ,Ног25сго11Ваг, 

0,0, 16, 16, 

noVertConstrain, noHorzConstrain, (Ø, Ø, 0, 0) 


), 


'Sclr^, ‘plot’, 

(0, 0), (400, 400), sizeSuperView, sizeSuperView, 
shown, enabled, 

View ("TPlotView”), 

‘plot’, 'qsiv', 


0, 0), 


(үм 18, 


Үн 19/, 


enabled, 


(325, 0), (75, 160),sizeFixed,sizeFixed, shown, enabled, 
View (“TSolutionView”)) a 
e 
«зы?» 


© The Best of MacTutor, Vol. 5 


Intermediate Mac'ing 


‘snd ' Zoundz Great! 


Kirk Chase 
II Anaheim, CA 
fun Volume 5, Number 9 


Zoundz 1.0 


Piano Lessons—Yech! 

When I was a boy, my mother made me take piano lessons 
(a fate that has fallen upon many young boys). I wasn't too 
interested in the piano, so I soon traded the ivory keyboard for the 
Qwerty keyboard. I can still hear my mother telling me that I'll 
regret the day I stopped playing the piano; I didn't think so—until 
now. 

I wanted to add sound to an application I was writing. Not 
knowing anything about sound other than the simple beep, I 
decided the Macintosh 'snd * resource was my next attack of 
study. So after an evening with Inside Macintosh, Vol. 5, I 
decided I had to be a MIDI maniac to understand a lot of the 
information found there, but I did manage to get a grasp on some 
of the simpler elements. So here is a simple overview. 

To make a sound, you basically create a sound channel to a 
particular synthesizer and pass it a list of sound commands 
which, among other things, generate sounds—simple. A synthe- 
sizer allows music to be played in a certain way; there is currently 
a note synthesizer, a wave synthesizer, a sampled sound synthe- 
sizer, and some MIDI synthesizers. Which one you use depends 
on how you are going to generate the sound. I chose the note 
synthesizer for my sound generating application. 

A sound channel is a record that holds information for 
processing the sound. It contains modifiers, call-back proce- 
dures, and a queue of sound commands. The sound commands 
are in a ‘snd ‘ resource format. 


The ‘snd ' Resource 

The ‘snd * resource has currently two types. The second type 
is used for representing an instrument or digitally recorded 
sound. Type one is used by us non-MIDI people. The first word 
in the ‘snd ‘ resource specifies this format type, 1 or 2. I use 
format type 1. 

The second word tells how many synthesizers and modifiers 
that follow. A modifier, for a quick explination, is some code that 
alters the sound generated in some manner. I use this second 
word to open up a note synthesizer. This word is followed by a 
word identifying the synthesizer and a long integer giving the 
initialization procedure, if any. This is repeated for each synthe- 
sizer and modifier as specified in the second word. 

After that, there is a word telling how many sound com- 
mands are to follow. Then the sound commands and any needed 
data are given. The format of the sound command is a word 
specifying which sound command, another word for param 1, and 
a long for param2. If this is all confusing, see figure 1. 


Sound Commands 
For my application, I use the simple note synthesizer. Out 
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'snd ' format = 1 


number of synthesizers/ 
modifiers = 1 


Figure 1. ‘snd ‘ Resource Format 


of all the commands that generate sound, the note synthesizer 
recognizes only the note, rest, quiet, frequency, amplitude, and 
timbre commands. I use only the note, timbre, rest, and quiet 
commands in my application. 

The note command has the ability to specify the pitch, 
amplitude, and duration. To further confuse matters, the pitch 
may be specified in two ways. The first way is to use a value 
between 0 and 127. This is then converted to a piano key (60 is 
middle С; 61 is C#). The other way is to give the actual 
frequency. I use the first way. The amplitude (0...255) is also 
added to the pitch and stored in the long (See figure 2). The 
duration, param], is specified in milliseconds. 


AA = Amplitude (0...255). Put in the high 
order byte of a long integer. 

PP = Pitch (0...127). Put in low order byte 
of a long integer. 

Add two long integers together and assign to 
param2 of sound command 


АА000000 
%000000РР 
=ААООООРР 


Figure 2. Combining Pitch апа Amplitude 


Zoundz 1.0 
Zoundz gives the user the ability to draw a wave type 
description of the sound. There are four graphs the user draws to 
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generate the sound—frequency,amplitude, duration,and timbre. 
Each vertical column isa note. You may also control the display 
of each graph (the drawing goes faster if you turn off the drawing 
of the other graphs). 

The user may specify the exact values of a particular note. 
Use the scroll bar below the graphs to move the note you wish to 
modify to the left edge of the rectangle. The individual values 
may then be adjusted using the scroll bars in the upper right 
corner of the window. You may also specify which note to start 
and end your selection. When you are ready, just press the “Play 
Sound” button (be sure to specify the selection range). Figure 3 
shows the Zoundz window. 

é File Edit Entend 
EM- 


r 


B (© Frequency 
mO Amplitude 
IO Duration 
O Timbre 


Play Sound 


Music Selection View Graph 
Start: 1 PS Frequency 
64 Amplitude 
64 Duration 
& Timbre 


End: 23 
Ко i D E O 


SR СУ 


Figure 3. Zoundz Window 


Some editing shortcuts can be found under the "Extend" 
menu. Just set the selection range and select one of the menu 
items under this menu. The value selected in the menu of the 
current note (leftedge) is given to the notes in the selection range. 

When you save the sound, the values for each of the 100 
possible notes are saved in the data fork. In the resource fork, a 
‘snd ‘ resource is created with your sound. The name is the same 
as the one you gave to the file, and its ID=9000. Just use ResEdit 
to paste the sound into the system file (you may wish to give it a 
new ID number). You may also geta printed dump of your ‘snd ' 
resource by selecting the print option from the "File" menu. 

Zoundz is pretty nice. It handles Finder startups for the 
documents to either print or open. It gives us non-musicians the 
chance to sketch our sound. Zoundz is not very good at producing 
composed music. I did however get it to play “Happy Birthday". 
Try drawing patterns and listen to the outcome. You mightcreate 
something that zoundz good. 


Listing: MyGlobals 


unit MyGlobals; 
interface 
uses 
PrintTraps, Sound; 
const 
L-Apple = 1001; 
MI_About_Zoundz = 1; 
L.File = 1002; 
MI_New = 1; 
MI_Open = 


(Menu list) 
(Menu list) 


2; 
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Debug Windows 


20ипӣ2.т 


Options File (by build order) Size 
Runtime lib 18258 
Interface 116 8104 
PrintCalls 1% 1096 
PrintTraps.p 

Sound.p 

Mu Globals .Pas 

My Sound Pas 

init TheMenus Pas 

Message Pas 

save_changes Pas 

MyFileStuff Pas 

MyPrintStuff Pas 

About Pas 

Untitled Pas 

Handle TheMenus Pas 

Zoundz .Pas 


DNVR 
DNVR 
ОМУК 
DNVR 
DNVR 
DN VR 
DN VR 
DNVR 
ОМУК 
ОМУК 
DNVR 
DNVR 
DNVR 


Figure 4. Zoundz Build Order 


MI_Close = 4; 
MI_Save = 5; 
MI_Save_As = 6; 
MI_Page_Setup = 8; 


MI_Print = 9; 
MI.Quit = 11; 
L-Edit = 1003; (Menu list) 
MI_Undo = 1; 
MI_Cut = 3; 
MI_Copy = 4; 
MI_Paste = 5; 
L_Extend = 1004; (Menu list) 
MI_Frequency = 1; 
MI_Amplitude = 2; 
MI_Duration = 3; 
MI_Timbre = 4; 
1_Үеѕ = 1; 
I_Cancel = 2; 
I_No = 3; 
type 
DocPtr = ^DocRec; 
DocRec = record (Sound Doc Structure} 


Freq, Amp, Dur, Timbre: array[1..100] of integer; 
EndValue, StartValue: integer; 
end; 

MuSoundRec = packed record (Snd structure) 
format: integer; 
SunthCount: integer; 
SynthType: integer; 
SynthInit: longint; 
CommandCount: integer; 
MuSounds: array[1..202] of SndCommand; 


end; 
MySoundPtr = ^MySoundRec; 
MySoundHdl = ^MySoundPtr; 
var 


FreqText, AmpText, DurText, TimbreText: Str255; 
NoteText, StartText, EndText: Str255; 
NoteIndex, DrawTool: integer; (Indices) 

MyDoc: DocPtr; (Sound Document) 

Dirty: boolean; 

NoteRect, FreqRect, AmpRect, DurRect, TimbreRect: Rect; 
EndRect, StartRect, NotePallete: Rect; 
MyHandle: Handle; (Various Handles) 
MySoundHandle: MySoundHd!; 

AppleMenu: MenuHandle; (Menu handle) 

M.File: MenuHandle; 

M Edit: MenuHandle; 

M Extend: MenuHandle; 
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MuWindow: WindowPtr; 
FileName: str255; 
volRefNum, FileStatus: integer; 
theSquare, theWatch: CursHandle; (Cursor Stuff) 
ThePrintRec: THPrint; (Printing Stuff} 
ThePrintPort: TPPrPort; 
PrintStatus: TPrStatus; 
PageRect: rect; 

implementation 

end. 


Listing: 


(Window pointer) 
(File Stuff) 


MySound.pas 


unit MySound; 
interface 
uses 
PrintTraps, Sound, MuGlobals; 
(creates a ‘snd ' resource) 
procedure CreateSndResource (StartSel, EndSel: integer); 
implementation 
procedure CreateSndResource; 
var 
i, j: integer; 
amplong, freqlong: longint; 
lastTimbre: integer; 
theErr: OSErr; 
theSize: integer; 


begin 
lestTimbre := -1; 
1f HandleC(MySoundHandle) € nil then 
begin 
DisposHandleCHandleCMySoundHandle2); 
DisposHandle(MyHandle); 
end; 
MySoundHandle := 


MySoundHd1 (NewHand1e(sizeof (MySoundRec))); 
with MySoundHandle^^ do 
begin 
format := 1; (set up header stuff) 
SynthCount := 1; 
SynthType := 1; 
SynthInit := Ø; 
with MyDoc* d 
begin 
j := 9; 
for i := StartSel to EndSe1 do 
begin (get sound commands) 
979320 
if timbreli] © lastTimbre then 
begin 
MySounds[jl.cmd := timbreCmd; 
MySounds[{j].parami := timbreli]; 
MySounds[j].param2 :- 0; 
lastTimbre := timbreli]; 
2557 %%; 
end; (of timbre command) 


if freq[i] = 128 then (is it a rest?) 
begin 
MuSounds[j].cmd := restCmd; 


MySounds[j].param1 := dur[i]; 
MySounds[j].param2 :- Ø; 
елд 
else (го, regular note) 
begin 
ampLong := ampli]; 
ampLong := BitAnd(BitShiftCampLong, 24) 
$FF000000); 
freqLong := BitAnd(freq[i), %000000ҒҒ); 
MuSounds[j].cmd := noteCmd; 
MySounds[j].param! := durlil; 
MySounds[jl.param2 := ampLong + 
freqLong; 
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М 


end; 
end; (of for loop) 
end; (with MuDoc) 
ji Jd 
MgSounds[jl.cmd := noteCmd; (turn off sound) 
MySounds[j].param! 
MySounds[j].param2 
J Jg 
MySounds[jl.cmd := quietCmd; 
MySounds[j].param1 := Ø; 
MySounds[jl.param2 :- Ø; 
CommandCount := j; 
end; ( of with MuSoundHandle) 
theSize := 12 + (j * 8); 
MuHandle := Handle(MuSoundHandle); 
theErr :- HandToHand(MuHandle); 
SetHandleSize(MuHandle, Size(theSize)); 
end; ( of CreateSndResource) 
end. 


2 


0; 


Listing: InitTheMenus.pas 
unit InitTheMenus; 
interface 
uses 
PrintTraps, Sound, MuGlobals; 
procedure Init. My.Menus; (Initialize the menus) 


implementation 
procedure Init Му Menus; (Initialize the menus) 
const 
Menu! = 1001; (Menu resource ID) 
Menu2 = 1002: (Menu resource ID) 
Menu3 = 1093; (Menu resource ID) 
Menu4 = 1004: 
begin (Start of Init.My. Menus) 
ClearMenuBar ; (Clear any old menu bars} 
AppleMenu := GetMenu(Menu1); 


InsertMenuCAppleMenu, 0); 
AddResMenuCAppleMenu, ‘DRVR’); 
MFile := GetMenu(Menu2); 
InsertMenu(M.File, 0); 
M_Edit := GetMenu(Menu3); 
InsertMenu(M_Edit, 0); 
M-Extend :- GetMenu(Menu4); 
InsertMenu(M. Extend, 0); 
DrawMenuBar ; 
end; (End of procedure Init. My. Menus) 
end. 


Listing: Message.pas 
unit Message; 
interface 
procedure A Message (50, 51, 52, 53: str255; var theltem: 
integer); 
implementation 
procedure A_Message; 
var 
itemHit: Integer; 
AlertResHandle: AlertTHnd1; 
tempRect: Rect; 
begin (Start of alert handler) 
РагапТех((50, 51, 52, 53); 
AlertResHandle :- AlertTHndlCGetResourceC'ALRT^, 422; 
HLockCHandleCAlertResHandle)); 
tempRect := AlertResHandle^^.boundsRect; 
tempRect.Left := (C(screenBits.Bounds.Right - 
screenBits.Bounds.Left) - CtempRect.Right - tempRect.Left)) 
div 2; (Center Horz) 
tempRect.Bottom := tempRect.Top + 
(AlertResHandle^^.boundsRect.Bottom - 
AlertResHandle**^ .boundsRect . Top); 
tempRect.Right := tempRect.Left + 
(AlertResHandle*^^.boundsRect.Right - 
AlertResHandle^* .boundsRect .Lef t); 
AlertResHandle^^.boundsRect := tempRect; 


theltem := NoteAlert(4, nil); 
HUnLockCHandleCATlertResHandle)); 
end; (End of procedure) 
end. (End of unit) 


Listing: save-changes.pas 
unit save_changes; 
interface 
function D_save_changes: integer; 
implementation 
const 
I_Yes = 1; 
I_Cancel = 2; 
I_No = 3; 
Ix = 4; 
var 
ExitDialog: boolean; 
DoubleClick: boolean; 
MyPt: Point; 
MyErr: OSErr; 
function D. save. changes; 
var 
GetSelection: DialogPtr; 
tempRect: Rect; 
DTgpe: Integer; 
DItem: Handle; 
itemHit: Integer; 
procedure Refresh Dialog; 
ver 
rTempRect: Rect; 
begi 


n 
SetPort(GetSelection); (Point to our dialog window) 
GetDItem(GetSelection, I.Yes, DType, DItem, tempRect); 
PenSize(3, 3); 
InsetRectCtempRect, -4, -4); 
FremeRoundRectCtempRect, 16, 16); 
PenSizeC1, 1); 
end; 
begin (Start of dialog handler) 
GetSelection :» GetNewDialog(3, nil, Pointer(-1)); 
ShowWindowCGetSelection); 
SelectWindowCGetSelection); 
SetPortCGetSelection); 


Refresh. Dialog; 
ExitDialog := FALSE; 
repeat 


ModalDialog(nil, itemHit); 
D_save_changes := itemHit; 
if (ItemHit = I_Yes) or (ItemHit = I. Cancel) or 
CItemHit = I_No) then 
ExitDialog := TRUE; 
until ExitDialog; 
DisposDialog(GetSe lection); 
end; 
end. (End of unit) 


Listing: MyFileStuff.pas 
unit MyFileStuff; 
interface 
uses 
PrintTraps, Sound, MyGlobals, Message, MySound; 
procedure doSave; 
procedure doSaveAs; 
procedure OpenFile; 
procedure doOpen; 
implementation 
const 
SFPutLeft = 82; 
SFPutTop = 50; 
myType = ‘ZZDC’; 
myCreator = 'KCZZ'; 
var 
SFPutPt: Point; 
theReply: SFReply; 
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refNum, resRef: integer; 
bytes: longint; 

title: str255; 
theLength: longint; 
theErr: OSErr; 

theItem: integer; 
oldHandle: Handle; 


function HandleError (theStr: Str255; theError: OSErr; chk, 
chksum: integer; CloseIt: boolean): boolean; 
var 
STemp: str255; 


gin 
{f (theError € noErr) then 
begin 
А Message(theStr, '^, '/, ‘’, theItem); 
1f CloseIt then 


begin 
theErr := FSCloseCrefNum?; 
theErr := FlushVol(nil, VolRefNum); 
end; 
HandleError := true; 
end 
else if (chk O chksum) then 
begin 


A_Message(theStr, ‘Checksum Error’, ‘’, '', theItem); 
1f CloseIt then 
begin 
theErr := FSClose(refNum); 
theErr := FlushVol(nil, "olRefNum); 


end; 
HandleError := true; 
end 
else 
HandleError := false; 
end; 


procedure doSave; 
begin 
if VolRefNum = 0 then 
begin (bad volume reference number) 
A_Message( ‘Bad Volume Number’, ’’, '', ‘’, theItem); 
ExitCdoSave ); 
end 
else (good volume reference number} 
begin 
theErr := FSOpen(FileName, VolRefNum, refNum); 
if HandleError( ‘Could Not Open File’, theErr, 0, 8, 
false) then 
Exit(doSave) 
else (file was open ok) 
begin 
theErr := SetFPos(refNum, FSFromStart, 0); 
1f HandleError( ‘Could Not Open File Position’, 
theErr, 8, 8, true) then 
ExitCdoSave ) 
else {ready to go} 
begin 
bytes := sizeof (DocRec); 
theLength := bytes; 
theErr := FSWriteCrefNum, bytes, 
ptr(MyDoc)); 
if HandleError( ‘Trouble Writing To File’, 
theErr, bytes, theLength, true) then 
ExitCdoSave); 
end; 
end; (of file open ok) 
theErr := FSCloseCrefNum); 
theErr := FlushVol(nil, Vol3efNum); 
theErr := SetVol(nil, VolRefNum); 
CreateResF i leCF ileName?; 
resRef := OpenResFile(FileName); 
if resRef = -1 then 
begin (could not be opend} 
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A_Message( ‘Could not write sound to’, FileName, 
^^, 4, theltem); 
ExitCdoSave); 
end 
else (ready to write out sound) 
begin 
OldHandle := GetResource(‘snd ', 9000); 
if OldHendle © nil then 
begin (existing sound to remove) 
RmveResource(01dHandle); 
DisposHandleCOldHandle); 
UpdateResF i leCresRef ); 
end; 
CreateSndResource(MyDoc^ .StartValue, 
MyDoc* .EndValue); 
AddResource(MyHandle, ‘snd ', 9000, FileName); 
UpdateResF ile(resRef ); 
CloseResF i leCresRef ); 
DisposHandleCMyHandle); 
DisposHandleCHandle(CMySoundHandle)); 
end; 
end; ( of good vol ref num) 
end; (of doSave) 


procedure doSave4s; 
begin 
SetPt(SFPutPt, SFPutLeft, SFPutTop); 
GetWTitleCMyWindow, title); 
SFPutFileCSFPutPt, ‘Save Zoundz as..’, title, nil, theRe- 
ply); 
if theReply.good then 
begin 
theErr := CreateCtheReply.fname, theReply.vRefNum, 
myCreator, myType); 
if theErr © noErr then (duplicate or problem) 
begin 
if theErr = dupFNerr then 
begin (duplicate) 
theErr := FSDelete(theReply. fname, 
theReply.vRef Num); 
if theErr «> noErr then 
begin (cannot delete file} 
A_Message( ‘Cannot Delete File.’, ‘’, '', 
^^, thel tem); 
ExitCdoSaveds); 
end; 
theErr := CreateCtheReply. fname, 
theReply.vRefNum, myCreator, myType); 
if theErr € noErr then 
begin (error in creating after deleting 
duplicate) 
A_Message( ‘Cannot Create’, 
theReply.fname, '', ‘’, theItem); 
ExitCdoSaveAs); 
end; 
end 
else ( a problem) 
begin 
A_Message( ‘Cannot Create’, theReply.fname, 
'^, 4, Же tem); 
ExitCdoSaveAs); 
end; 
end (duplicate or problem) 
else (ready to save) 
begin 
VolRefNum := theReply.vRefNum; 
FileName :- theReply. fname; 
SetWTitleCMyWindow, FileName); 
theErr := FlushVol(nil, VolRefNum); 
doSave; 
end; (ready to save) 
end; (good reply) 
end, 
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procedure OpenFile; 
begin 
theErr := FSOpen(FileName, VolRefNum, refNum); 


1f HandleError( ‘Could Not Open File’, theErr, 0, 0, false) 
then 
ExitCOpenF ile) 
else (file was open ok) 
begin 
theErr := SetFPos(refNum, FSFromStart, 0); 
1f HandleError( ‘Could Not Open File Position’, 
theErr, 0, 0, true) then 
begin ` 
VolRefNum := 0; 
ExitCOpenFile); 
end 
else (ready to go) 
begin 
bytes := sizeof(DocRec); 
theLength := bytes; 


theErr :- FSRead(refNum, bytes, ptr(MuDoc)); 
if HandleError( ‘Trouble Reading File’, theErr, 
bytes, theLength, true) then 


begin 
VolRefNum := 0; 
ExitCOpenF ile); 
end, 
end, 


end; (of file open ok) 

theErr :- FSCloseCrefNum); 
theErr := FlushVol(nil, VolRefNum); 
MyWindow := nil; 
NoteText := '1^; 
NumToString(MyDoc* .StartValue, StartText); 
NumToString(MyDoc* .EndValue, EndText); 
NumToString(MyDoc*.freql1], FreqText); 
NumToString(MgDoc^ .amp[ 1], AmpText); 
NumToStr ingCMyDoc^ .dur [1], DurText); 
NumToString(MyDoc^ .timbret 1], TimbreText); 
NoteIndex := 1; 
DrawTool := 1; 
MySoundHandle := nil; 
MuHandle := nil; 

end; 


procedure do0pen; 
var 
theTypes: SFTypeList; 
begin 
SetPtCSFPutPt, SFPutLeft, SFPutTop); 
theTypes[2] := myType; 
SFGetFileCSFPutPt, ‘Open Zoundz file.^, nil, 1, theTypes, 
nil, theReply); 
VolRefNum := 0; 
if theReply.good then 
begin 
VolRefNum := theReply.vRefNum; 
FileName := theReply.fName; 
OpenFile; 
end; 
end; 
end. 


Listing: MyPrintStuff.pas 
unit MyPrintStuff; 
interface 
uses 
PrintTreps, Sound, MyGlobals, MySound, Message; 
procedure doSetUp; 
procedure doPr int; 
implementation 
var 
(һе tem: integer; 
procedure doSetUp; 
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var 
confirmed: boolean; 
begin 
PrOpen; 
InitCursor; 
confirmed := PrValidate(ThePr intRec); 
confirmed := PrSt1Dialog(ThePrintRec?; 
1f PrError © noErr then 
A-MessageC'Problem with style dialog’, °’, '', “°, 
theItem) 
else 
PageRect := ThePrintRec^^.prInfo.rpage; 
PrClose; 
end; 


procedure PrintIt; 
var 
lef tEdge, lineTop, lineBottom, lineSize: integer; 
title: str255; 


i: integer, 
procedure NumToHexString (n: longint; var s: str255); 
var 
d, i: integer; 
begin 
S өш ШЫ 
i := 32; 
while i> 0 do 
begin 
d := BitAnd(n, 15); 
n := BitShift(n, -4); 
і = i - 4; 
1f d < 10 then 
s := сопсаїСсћСогас*0/) + d), 5) 
else 
s := concatCchrCordC'A^) + d - 10), s); 
end; 


end; 


procedure LineFeed; 

begin 
lineTop := lineTop + lineSize; 
lineBottom := lineBottom + lineSize; 
MoveToCleftEdge, lineBottom); 

end; 


procedure Pr intHeader ; 
var 
61: str255; 


s] := 'Snd name is "'; 

s1 := concat(sl, title, '"'); 
MoveToCleftEdge, lineBottom); 
TextFace({bold]); 
DrawString(s 1); 
TextFaceCL12; 
LineFeed; 
LineFeed; 

end; 


procedure PrintFirstPart; 
var 
61, 52: str255,; 
num: longint; 
begin 
num := MySoundHandle**.format; 
51 :: 'Snd Format = '; 
NumToString(num, s2); 
S1 := сопса{С51, s2); 
DrawString(s1); 
LineFeed; 
num := MySoundHandle**.SynthCount; 
51 := 'Synthizers = '; 
NumToString(num, 522; 
sl := concat(sl, 52); 
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DrawString(s1); 
LineFeed; 
num := MySoundHandle** .SynthType; 
51 := ‘Snd Format = '; 
NumToString(num, 52); 
si := concat(s!, 52, * CnoteSynth)’); 
DrawString(s1); 
LineFeed; 
num := MySoundHandle** .SynthInit; 
sl := ‘Snd Initialization = '; 
NumToHexString(num, $2); 
sl := concat(sl, ‘$’, 52); 
DrawString(s 1); 
LineFeed; 
num := MySoundHandle*^*^ .CommandCount; 
s1 := ‘Number of Sound Commands = '; 
NumToString(num, 52); 
51 := concat(sl, 52); 
DrawString(s1); 
LineFeed; 

DrawString(’ # cmd param | param2 Description’); 
MoveToCleftEdge, lineBottom + 2); 
LineToCPageRect.right, lineBottom + 2); 
MoveToCleftEdge, lineBottom); 
LineFeed; 

end; 


procedure PrintNote Ci: integer); 
var 
61, 52, 53: str255; 
num: longint; 
c, pi: integer; 
p2: longint; 
begin 
c := MySoundHandle** .MySounds[ i ) .cmd; 
pi := MySoundHandle*^*^ .MySounds[ i ). peram; 
= MySoundHandle** .MySounds[ i ).param2; 
num := i; (put index number) 
NumToString(num, $1); 
if i < 10 then 
sl := concat(' ’, $1); 
if i < 100 then 
sl := concat(’ ”, s1); 
51 := concat(sl, ‘ 7); 
NumToString(c, s2); 
if c < 10 then 
S2 := concat(’ ’, 52); 
51 := concat(s!, s2, ' $7); 


NumToHexString(p1, 52); 
NumToHexString(p2, 53); 
s1 := concat(sl, 52, ' $’, 53, ' 7); 
case c of 
quietCmd: 
begin 
S1 := concat(s1, ‘quietCmd - The End’); 
end; 
timbreCmd: 
begin 
sl := concat(s1, ‘timbreCmd - Value ^); 
NumToString(p1, 522; 
s1 := сопса{С51, 522; 
end; 
restCmd: 
begin 
si := concat(sl, 'restCmd - Rest ’); 
NumToString(p1, $2); 
sl := сопсаї (51, s2, ' milliseconds’); 
end; 
noteCmd: 
begin 
51 := concat(sl, ‘noteCmd - Note °); 
num := BitAnd(p2, $FF); 
NumToString(num, s2); 
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51 := concat(si, s2, ', Amp. 7); 
num := BitAnd(BitShift(p2, -24), $FF); 
NumToString(num, 62); 
S1 := concat(si, s2, ', Duration ”); 
NumToString(p1, s2); 
sl := concat(sl, s2, ‘ milliseconds’); 
end; 
otherwise 
begin 
51 := concat(sl, ‘Unknown sound command’); 
end; 
end; 
DrawStr ing(s1); 
end; 


begin 
(set up position} 
PenNormal ; 
TextFont(monaco); 
TextFace([]); 
TextSizeC9); 
lineTop := PageRect.top; 
lineSize := 12; 
lineBottom := lineTop + lineSize; 
leftEdge := 30; 
GetWTitleCMyWindow, title); 
PrOpenPage(ThePrintPort, nil); (open page) 
PrintHeader; (print header) 
PrintFirstPart; (print first part) 
for i := 1 to MySoundHandle^*^ .CommandCount do 
begin 
if lineBottom > PageRect .bottom then 
begin (if position is too great) 
PrClosePage(ThePr intPort); (close page) 
PrOpenPage(ThePrintPort, nil); (open page) 
lineTop := PageRect. top; 
lineBottom := lineTop + lineSize; 
PrintHeader; (print header) 
DrawString(’ 8 cmd param 1 param2 Description’); 
MoveToCleftEdge, lineBottom + 2); 
LineToCPageRect.right, lineBottom + 2); 
MoveToCleftEdge, lineBottom); 
LineFeed; 
end; 
PrintNoteCi); (print note) 
LineFeed; 
end, 
PrClosePage(ThePr intPort); (close page) 
end; 


procedure doPrint; 
var 
DoIt: boolean; 
myPrPort: TPPrPort; 
savePort: GrafPtr; 
copies, count: integer; 
begin 
GetPort(savePort); 
SetCursor (arrow); 
PrOpen; 
if PrError = 
begin 
DoIt := PrValidate(ThePrintRec); 
DoIt := PrJobDialog(ThePr intRec); 
if PrError © noErr then 
A_Message( ‘Problem with job dialog’, '', °’, '', 


noErr then 


theItem); 
if DoIt then 
begin (print document) 
SetCursor(CtheWatch^^); 
ThePrintPort := PrOpenDoc(ThePrintRec, nil, nil); 
if PrError = noErr then 
begin (ok port) 
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CreateSndResource(MyDoc* .StartValue, 
MyDoc* .EndValue); 


copies :- ThePrintRec^^.prJob. iCopies; 
PageRect := ThePrintRec^^.prInfo.rpage; 
for count := 1 to copies do 


begin (copies loop) 
PrintIt; (print the document) 
end; (copies loop) 
DisposHandleC(MyHandle); 
DisposHandleCHandleCMySoundHandle)); 


MyHandle := nil; 
MySoundHandle := nil; 
end 


else (bad port) 
A-Message(C'Open Document Error’, ‘’, '', 9, 
(һе tem); 
PrCloseDoc(ThePr intPort); 
16 (ThePrintRec**.prdob.buDocLoop = bSpoolLoop) 
and (PrError = noErr) then 
PrPicFileCThePrintRec, nil, nil, nil, 
PrintStatus); 
end; (printing document} 
end; 
PrClose; 
SetPort(savePort); 
SetCursor (arrow) 
end; 
end. 


Listing: 

unit About; 

interface 
procedure D About ; 

implementation 
const 


About . pas 


var 
ExitDialog: boolean; 
DoubleClick: boolean; 
MyPt: Point; 
MyErr: OSErr; 


procedure D About; 
var 
GetSelection: DialogPtr; 
tempRect: Rect; 
ОТуре: Integer; 
DItem: Handle; 
itemHit: Integer; 
procedure Refresh Dialog; 
var 
rTempRect: Rect; 
begin 
SetPort(GetSelection); 
GetDItemCGetSelection, І.0К, DType, DItem, tempRect); 
PenSize(3, 3); 
InsetRectCtempRect, -4, -4); 
FrameRoundRect(tempRect, 16, 16); 
PenSizeC1, 1); 
end; 
begin 
GetSelection := GetNewDialog(2, nil, Pointer(-12); 
tempRect := GetSelection^.portRect; 
tempRect.Top := (CscreenBits.Bounds.Bottom - 


screenBits.Bounds.Top) - (tempRect Bottom - tempRect.Top)) div 


2; 

tempRect.Left :- ((screenBits.Bounds.Right - 
screenBits.Bounds.Left) - CtempRect.Right - tempRect.Left)) 
div 2; 

MoveWindow(GetSelection, tempRect.Left, tempRect.Top, 
TRUE); 

ShowWindow(GetSelection); 
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SelectWindow(GetSelection); 
SetPort(GetSelection); 
Refresh_Dialog; 

ExitDialog := FALSE; 


repeat 
ModalDialog(nil, itemHit); 
GetDItem(GetSelection, itemHit, DType, DItem, tempRect); 
if CItemHit = I_0K) then 
begin 
ExitDialog := TRUE; 
end; 
until ExitDialog; 
DisposDialog(GetSelection); 
end; 
end. (End of unit) 


Listing: Untitled.pas 
unit Untitled; 
interface 
uses 
PrintTraps, Sound, MyGlobals, MySound; 
(Initialize us so all our routines can be activated) 
procedure Init_Untitled; 
(Close our window} 
procedure Close Untitled CwhichWindow: WindowPtr); 
(Open our window and draw everything) 
procedure Open_Untitled; 
(Update our window, someone uncovered a part of us) 
procedure Update_Untitled (whichWindow: WindowPtr); 
(Handle action to our window, like controls) 
procedure Do_Untitled (myEvent: EventRecord); 
implementation 
const 
B.Play.Sound = 
CB_Timbre = 16; 
CB_Duration = 15; 
CB_Amplitude = 14; 
CB_Frequency = 13; 
RB_Timbre = 20; 
RB.Duretion = 19; 
RB.Amplitude = 18; 
RB.Frequency = 17; 
I_DurationScrollbar = 41; 
I-AnplitudeScrollbar = 40; 
I-.FrequencyScrollbar = 39; 
I_TimbreScrollbar = 38; 
I-EndScrollbar = 31; 
I_StartScrollbar = 27; 
I-.NoteScrollbar = 12; 
var 
tempRect: Rect; (Temporary rectangle) 
sTemp: Str255; (Get text entered, temp holding) 
C_EndScrollbar: ControlHandle; 
C_StartScrollbar: ControlHandle; 
C.NoteScrollbar: ControlHandle; 
RiControl: array[1..4] of ControlHandle; 
C-Play-Sound: ControlHandle; 
C_Timbre: ControlHandle; 
C_Duration: ControlHandle; 
C- Amplitude: ControlHendle; 
C_Frequency: ControlHandle; 
C_DurationScrollbar: ControlHandle; 
C-AmplitudeScrollbar: ControlHandle; 
C_FrequencyScrollbar: ControlHandle; 
C_TimbreScrollbar: ControlHandle; 


26; (Button ID) 
(Checkbox IDs) 


(Radio IDs) 


(Scroll bar IDs) 


(Initialize us so all our routines can be activated) 
procedure Init. Untitled; 


var 
i: integer; 
begin (Start of Window initialize routine) 
MyWindow := nil; 
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NoteText := ‘1’; (Init Texts) 
StartText := '1'; 
EndText := '1'; 
FreqText := ‘0’; 
AmpText := ‘0’; 
DurText := 0” 
TimbreText := ‘8’; 
NoteIndex := 1; (Init Miscellaneous) 
DrawTool := 1; 
MyDoc* .EndValue := 1; 
Муос“ .StartValue := 1; 
MySoundHandle := nil; 
MyHandle := nil; 
volRefNum := 0; 
for i := 1 to 100 do (initialize arrays) 
begin 
MyDoc^ .freqli] := 0; 
MyDoc* .amp[ i] 0; 
MuDoc .dur [i] 0; 
MuDoc .timbre[i] := 0; 
end; 
end; (End of Init_Untitled) 


(Close our window) 
procedure Close.Untitled; 
begin 
{f (MyWindow © nil) and ((MuWindow = whichWindow) or 
(ord4(whichWindow) = -1)) then 
begin 
DisposeWindow(MuWindow); 
MuWindow := nil; 


end; 
end; (End of Close_Untitled) 


(draws a square according to the pattern) 
procedure DrawSquare (vert, horiz: integer; thePat: 
pattern); 
ver 
theSquare: rect; 
begin 
SetRect(theSquare, horiz, vert, horiz + 18, vert + 10); 
InSetRect(theSquare, 1, 1); 
PenNormal; 
FillRectCtheSquare, thePat); 
FraemeRectCtheSquare); 
end; (of DrewSquare) 


(Takes a point and returns vertical end horizontal values) 
procedure Unconvert (thePoint: Point; range: integer; var 
value, column: integer); 


var 
Lvalue, Lrange: longint; 
begin 
if thePoint.h < 5 then (out of range) 
column := -1 


else (get column) 
column := CthePoint.h - 5) div 10; 
if column > 22 then (out of range) 


column := -1; 
if (thePoint.v < 5) or CthePoint.v > 260) then 
value := -1 (out of range) 
else 
begin (get value) 
Lvalue := thePoint.v - 5; 


Lrenge := range; 


Lvalue := Lvalue * Lrange; 
value := LValue div 255; 
end; 
end; (of unconvert) 
(==============================2==) 
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(returns vertical position) 
function Convert (value, range: integer): integer; 


var 
Lvalue, Lrange: longint; 
begin 
Lvalue := value; 
LRange := range; 


Convert := ((Lvalue * 245) div Lrange) + 5; 
end; {of Convert} 


(Update our window, someone uncovered a part of us} 
procedure UpDate_Untitled; 
var 
SavePort: WindowPtr; (Place to save the last port) 
theValue, theTop, i, rangeStop, RangeStart: integer; 
begin 
if (MyWindow O nil) and (MuWindow = whichWindow) then 
begin 
GetPort(SavePort); (Save the current port) 
SetPort(MyWindow); (Set the port to my window) 
TextFont(systemFont); (Set the font to draw in) 


{ Draw DrawGraph Stuff) 

SetRect(TempRect, 245, 20, 355, 105); 

FrameRect(TempRect); (Frame this rectangle area) 

SetRect(tempRect, 265, 5, 345, 20); 

sTemp := ‘Draw Graph’; 

TextBox(PointerCord(@sTemp) + 1), length(sTemp), 
tempRect, teJustLeft); 

SetRect(tempRect, 248, 28, 258, 38); 

FillRectCtempRect, black); 

FremeRectCtempRect); 

SetRect(tempRect, 248, 48, 258, 58); 

FillRectCtempRect, dkgray); 

FrameRectCtenpRect); 

SetRectCtempRect, 248, 68, 258, 78); 

FillRect(tempRect, grau); 

FrameRect(tempRect); 

SetRect(tempRect, 248, 88, 258, 98); 

FillRectCtempRect, ltgray); 

FrameRect(tempRect); 

FrameRect(tempRect); 

TextBox(Pointer(ord(ëFreqText) + 1), 
length(FreqText), FreqRect, teJustLeft); 

TextBox(Pointer(ord(@AmpText) + 1), lengthCAmpText), 
AmpRect, teJustLeft); 

TextBox(PointerCord(@DurText) + 1), lengthCDurText), 
DurRect, teJustLeft); 

TextBox(Pointer(Cord(@TimbreText) + 1), 
length(TimbreText), TimbreRect, teJustLeft); 


( Draw a rectangle, ViewGraphRect ) 
SetRect(TempRect, 398, 198, 490, 
275); (left, top, right, bottom} 
FrameRect(TempRect); (Frame this rectangle area) 
SetRect(tempRect, 400, 175, 475, 190); 
sTemp := ‘View Graph’; 
TextBox(PointerCord(@sTemp) + 1), length(sTemp), 
tempRect, teJustLeft); 


( Draw a rectangle, NotePallete } 
PenPatCwhite); 
PaintRect(NotePallete); 
PenNormal ; 
FrameRect(NotePallete); (Frame this rectangle area} 
RengeStart := GetCt]lValue(C_NoteScrol lbar); 
RangeStop := RangeStart + 22; 
1f RangeStop > 100 then 

RangeStop := 100; 
for i := RangeStart to RangeStop do 

begin 

if GetCtlValue(C_Timbre) = 1 then 
begin 
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theValue := MyDoc*.timbre[i]; 
theTop := Convert(theValue, 254); 
DrawSquare(theTop, (i - RangeStart) * 10 + 5, ltgrau); 
end; 
if GetCtiValueCC. Duration) = 1 then 
begin 
theValue := MygDoc^.dur[i); 
theTop := Convert(theValue, 250); 
DrawSquareCtheTop, Ci - RangeStart) * 10 + 5, gray); 


eng; 
if GetCtlValue(C_Amplitude) = 1 then 
begin 
theValue := MyDoc*.amp[i]; 
theTop := Convert(theValue, 255); 
DrawSquare(theTop, Ci - RangeStart) * 10 + 5, dkgray); 


end; 
1f GetCtlValueCC Frequency) = 1 then 
begin 
theValue := MyDoc*.freqlil; 
theTop := Convert(theValue, 128); 
DrawSquare(theTop, Ci - RangeStart) * 10 + 5, black); 
end; 
end; 


(Music Selection Stuff} 

SetRect(tempRect, 255, 175, 365, 190); 

sTemp := ‘Music Selection’; 

TextBox(Pointer(ord(@sTemp) + 1), length(sTemp), 
tempRect, teJustLeft); 

SetRect(TempRect, 245, 198, 375, 275); 

FrameRect(TempRect); (Frame this rectangle area) 

TextBox (Pointer (Cord(@EndText) + 1), lengthCEndText), 
EndRect, teJustLeft); 

TextBoxCPointerCordC8StartText) + 1), 
length(StartText), StartRect, teJustLeft); 

SetRect(tempRect, 250, 235, 280, 250); 

sTemp := ‘End:’; 

TextBoxCPointerCordCésTemp) + 1), length(sTemp), 
tempRect, teJustLef t); 

SetRect(tempRect, 250, 195, 290, 210); 

sTemp := “Start: 2; 

TextBox(Pointer(ord(ësTemp) + 1), length(sTemp), 
tempRect, teJustLeft); 


(Draw Note Index) 

SetRectCtempRect, 370, 5, 410, 28); 

sTemp := 'Note:'; 

TextBox(PointerCord(@sTemp) + 1), length(sTemp), 
tempRect, teJustLef t); 

TextBoxCPointerCordCGNoteText) + 1), 
length(NoteText), NoteRect, teJustLeft); 

TextFont(applFont); (Set the default application font) | 


DrewControlsCMyWindow2; (Draw all the controls) 
SetPort(SavePort); (Restore the old port) 
end; (End for if (MyWindowOni 12) 
end; (End of Update. Untitled) 


(Open our window and drew everything) 
procedure Open. Untitled; 


begin 
if (MyWindow = nil) then 
begin 
MyWindow := GetNewWindowC1, nil, Pointer(-1)); 
SetPor tCMyWindow); 


( Make a button, Play Sound ) 

C-Plau-Sound := GetNewControlCB.Play.Sound, MyWindow); 
( Make a checkboxes ) 
C_Timbre := GetNewControl(CB_Timbre, MyWindow); 
C_Duration := GetNewControl(CB_Duration, MyWindow); 
C_Amplitude :- GetNewControlCCB Amplitude, MyWindow); 
C-Frequency := GetNewControl(CB_Frequency, MyWindow); 
( Make a radio buttons } 
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RIControl[4] := GetNewControl1(RB_Timbre, MyWindow); 


RiControl(3] := GetNewControlCRB.Duration, MyWindow); 


RiContro1[2] := GetNewControlCRB. Amplitude, MyWindow); 
RiContro1[1] := GetNewControlCRB. Frequency, MyWindow); 
( Make a scroll bars ) 
C-DurationScrollbar := 
GetNewControlCI.DurationScrollbar, MyWindow); 
SetCtlValueCC.DurationScrollbar, 
MuDoc . dur [NoteIndex]); 
C-AmplitudeScrollbar := 
GetNewControlCI.AmplitudeScrollbar, MyWindow); 
SetCtlValueCC.AmplitudeScrollbar, 
MuDoc . атр [NoteIndex]); 
C-FrequencyScrollbar := 
GetNewControlCI.FrequencyScrollbar, MyWindow); 
SetCtlValueCC.FrequencyScrol bar, 
MyDoc*. freq(NoteIndex]); 
C_TimbreScrollbar := 
MyW indow ); 
SetCtlValueCC.TimbreScrollbar, 
MyDoc^ .timbre[NoteIndex]); 
C-EndScrollbar := 
C_StartScrollbar := 
SetCtlValue(C_EndScrollbar, Муос“ .EndValue); 
SetCtlValueCC.StartScrollbar, MyDoc*.StartValue); 
C_NoteScrollbar := GetNewControlCI.NoteScrollbar, 
Мун indow); 
ShowWindowCMyWindow); 
Se lectWindow(MyWindow); 
end 
else 
SelectWindowCMyWindow); 
end; (End of Open. Untitled) 


(Handle action to our window, like controls) 
procedure Do. Untitled; 
var 
RefCon: longint; 
code: integer; 
theValue: integer; 
whichWindow: WindowPtr; 
myPt: Point; 
theControl: ControlHandle; 
MyErr: OSErr; 
tempRect: rect; 
newValue, NewPosition: integer; 


procedure Do_A_Button; 
begin 
HiliteControl(theControl, 10); 
RefCon := GetCRefCon(theControl); 
case RefCon of (Select correct button) 
B_Plau-Sound: (Play Sound, button) 
begin (start for this button) 
CreateSndResource(GetCtlValue(C_StartScrollbar), 
GetCtlValue(C-EndScrollbar)); 
MyErr := SndPlay(nil, MyHandle, false); 
DisposHandleCMyHandle?); 
DisposHandleCHandle(CMySoundHandle)); 
MyHandle :* nil; 
MySoundHandle := nil; 
end; (end for this button) 
otherwise 
begin (start) 
end; (end of otherwise) 
end; (end of case} 
HiliteControlCtheContro], Ø); (Lighten the button) 
end; (Handle a button being pressed) 


procedure Do. A Checkbox; 
var 
Index: integer; (Index used for radios) 
procedure Clear IRedioGroup; 
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GetNewControlCI-TimbreScrollbar, 


GetNewControlCI.EndScrollbar, MyWindow); 
GetNewControlCI.StartScrollbar, MyWindow); 


var 
Index: integer; (Index used for radios) 
begin (Start of the clear routine) 


for Index := 1 to 4 do (Step thru all radios) 
SetCtlValueCRiControl[Index], 0); 
end; (End of the clear routine) 
begin (Handle a checkbox being pressed) 
RefCon := GetCRefCon(theControl); 
theValue := GetCtlValueCtheContro12); 
theValue := CtheValue + 1) mod 2; 
InvalRect(NotePallete); 
case RefCon of 
CB.Timbre, CB Duration, CB Amplitude, CB Frequency: 
begin 
SetCtlValueCtheControl, theValue); 
end; (end for this checkbox) 
RB.Timbre: (Timbre , radio button) 
begin (start for this radio button) 
DrawTool := 4; 
Clear iRadioGroup; 
SetCtlValueCtheControl, 1); (Select this Radio) 
SetCtlValueCC.Timbre, 1); 
end; 
RB_Duration: (Duration , radio button} 
begin (start for this radio button) 
DrawTool := 3; 
Clear 1Вадіобгоир; (Clear Radio values) 
SetCtlValueCtheControl, 1); (Select this Radio) 
SetCtlValueCC.Duration, 1); 
end; 
RB_Amplitude: {Amplitude , radio button) 
begin (start for this radio button) 
DrewTool := 2; 
Clear 1RadioGroup; 
SetCtlValueCtheControl, 1); (Select this Radio) 
SetCtlValueCC. Amplitude, 1); 
end; 
RB_Frequency: (Frequency , radio button) 
begin (start for this radio button} 
DrawTool := 1; 
Clear iRadioGroup; 
SetCtlValueCtheControl, 1); (Select this Radio) 
SetCtlValueCC.Frequency, 1); 
end; 
otherwise 


end; (end of case) 
end; (Handle a checkbox being pressed} 


procedure Do. A. ScrollBer (code: integer); 
procedure HandleWScrollBar (code, Start, Stop, 
Increment, LIncrement: integer; theControl: ControlHandle); 
var 
theValue: integer; (Value of the scrollbar) 
MaxTick: longint; (Timer for repeat scrolling) 
FirstTime: boolean; (Flag to start scrolling) 
begin 
FirstTime := TRUE; 
while (StillDown or FirstTime) do 
begin (Timer used for repeat scrolling) 
FirstTime := FALSE; 
HiliteControlCtheControl, code); 


theValue := GetCtlValueCtheControl2; 
if (code = inUpButton) then 
begin 
theValue := theValue - Increment; 


if (theValue < Start) then 
theValue := Start; 


end; 
if (code = inDownButton) then 
begin 
theValue := theValue + Increment; 


if (theValue > Stop) then 
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theValue := Stop; (Bump at the stop value) 
end; 
if (code = inPageUp) then 
begin 
theValue := theValue - LIncrement; 
if (theValue < Start) then 
theValue := Start; 
end; 
if (code = inPageDown) then 
begin 
theValue := theValue + LIncrement; 


1f CtheValue > Stop) then 


theValue := Stop; (Bump at the Stop value) 
end; 
if (code = inThumb) then 
begin 
code :- TrackControlCtheControl, myPt, 


nil);{Let the 0S drag it around) 
theValue := GetCtlValueCtheControl); 
end; 
SetCtlValueCtheControl, theValue); (Set new state) 
MaxTick := TickCount + 9; 
repeat (Start of delay routine) 
until not (Button? or (TickCount > 
MaxTick2; (Exit when time up or mouse button up) 
HiliteControlCtheControl, 02; {Lighten the arrow) 
end; (End for StillDown) 
end; (End of handle scroll bar) 


begin (Handle a 5сго11Ваг being pressed) 
RefCon := GetCRefConCtheContro12; (get control refcon) 
TempRect := NotePallete; 
TempRect.left := 6; 
TempRect.right := TempRect.left + 8; 
case RefCon of (Select correct scrollbar) 
I_DurationScrollbar: (DurationScrollbar, scroll bar) 
begin 
dirty := true; 

HandleWScrollBarCcode, Ø, 258, 1, 10, theControl); 
theValue := GetCt1lValueCtheControl); 
MyDoc^.dur [NoteIndex] := theValue; 
NumToStringCtheValue, DurText); 
InvalRect(DurRect); 

end; 
I-AmplitudeScrollbar: (AmplitudeScrollbar, scroll bar) 
begin 
dirty := true; 

HandleWScrollBarCcode, Ø, 255, 1, 10, theControl); 
theValue := GetCtlValueCtheContro1); 
MyDoc^ .amp[NoteIndex] := theValue; 
NumToStringCtheValue, AmpText); 
InvalRectCAmpRect); 

end; | 
I-.FrequencyScrollbar: (FrequencyScrollbar, scroll! bar) 
begin 
dirty := true; 

HandleWScrollBarCcode, Ø, 128, 1, 10, theControl); 
theValue := GetCtlValueCtheContro1); 
MgDoc^ .freq(NoteIndex] := theValue; 
if theValue < 128 then 

NumToStringCtheValue, FreqText) 
else 
FreqText := ‘Rest’; 
InvalRect(FreqRect); 
end; 
I_TimbreScrollbar: {TimbreScrollbar, scroll bar) 
begin 
dirty := true; 

HandleWScrollBar(code, 0, 254, 1, 10, theControl); 
theValue := GetCtlValueCtheContro12); 
MyDoc^.timbre[NoteIndex] := theValue; 
NumToStringCtheValue, TimbreText); 
InvalRect(TimbreRect); 

end; 
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GetC 


be 


I.EndScrollbar:(EndScrollber, scroll bar) 
begin 
dirty := true; 
HandleWScrollBar (code, 
tlValueCC.StartScrollbar?, 100, 1, 10, theControl); 
theValue :- GetCtlValueCtheContro2); 
MyDoc^.EndValue := theValue; 
NumToStringCtheValue, EndText); 
TempRect := EndRect; 
end; 
I_StartScrollbar: (StartScrollbar, scroll bar) 
begin (start for this scroll bar) 
dirty := true; 

HandleWScrollBarCcode, 1, 100, 1, 18, theControl); 
theValue := GetCtlValueCtheContro12; 
MyDoc^.StartValue := theValue; 
NumToStringCtheValue, StartText); 
InvalRect(StartRect); 
SetCtlMinCC.EndScrollbar, theValue); 
theValue := GetCtlValueCC EndScrollbar); 
MyDoc^.EndValue := theValue; 
NumToString(theValue, EndText); 


TempRect := EndRect; 
end; 
I.NoteScrollbar:(NoteScrollbar, scroll bar) 
begin 


HandleWScrollBar(code, 1, 100, 1, 10, theControl); 
theValue :- GetCtlValueCtheContro); 
NoteIndex := theValue; 
NumToStringCtheValue, NoteText); 
InvalRect(NoteRect); 
SetCtlValueCC.DurationScrollbar, Муос“. аог [Note Index]); 
SetCtlValueCC.FrequencyScrollbar, MyDoc^.freq(NoteIndex1); 
SetCtlValueCC Ampl itudeScrollbar, MyDoc^.amp[NoteIndex1); 
SetCtlValueCC TimbreScrollbar, MyDoc^.timbre([NoteIndex1); 
NunToString(MyDoc^ . timbre(NoteIndex], TimbreText); 
NumToString(MgDoc*^ . диг [NoteIndex], durText); 
NumToStr ing(MyDoc* .amp[NoteIndex], ampText); 
1f MyDoc^.freq(NoteIndex] < 128 then 
NunToString(MgDoc^ .freq(NoteIndex], FreqText) 
else 
FreqText := ‘Rest’; 
InvalRectCdurRect); 
InvalRect(freqRect); 
InvalRectCampRect); 
InvalRect(timbreRect); 
TempRect := NotePallete; 
InsetRect(TempRect, 1, 1); 
end; (end for this scroll bar) 
otherwise 
begin 
end; 
end; (end of case) 
InvalRect(TempRect); 
end; (Handle a ScrollBar being pressed) 


gin (Start of Window handler) 
if (MyWindow € nil) then 
begin 
code := FindWindow(myEvent where, whichWindow); 
if (myEvent.what = MouseDown) and (MyWindow = 


whichWindow) then 


begin 
myPt := myEvent.where; (Get mouse position) 
Global ToLocal CmyPt); 
end; 
if (MyWindow = whichWindow) and (code = inContent) 
then 
begin 
code := FindControl(myPt, whichWindow, theCon- 
trol); 
1f (code = inUpButton) or (code = inDownButton) 
or (code = inThumb) or (code = inPageDown) or (code = 


inPageUp) then 
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Do_A_Scrol1Bar(code); (Do scrollbars) 
if (code <> 0) then(Check type of control} 
code := TrackControlCtheControl, myPt, 
п112; (Тгаск the control) 
if code = inButton then 
Do_A_Button; (Do buttons) 
1f code = inCheckBox then 
Do_A_Checkbox; (Do checkboxes} 
if PtInRect(myPt, NotePallete) then 
repeat 
dirty := true; 
case Drawlool of 
1: 
UnConvert(muPt, 128, newValue, NewPosition); 


UnConvert(muPt, 255, newValue, NewPosition); 


UnConvert(mgPt, 250, newValue, NewPosition); 
4: 
UnConvert(muPt, 254, newValue, NewPosition); 
end; 
1f (newValue € -1) and (newPosition © -1) 
then 
begin (still in NotePallete?) 
case DrawToo! of 
1: 
begin 
Муос“ .freg(GetCtlValueCC.NoteScrollbar) + NewPosition] :- 
newValue; 
1f NewPosition = 0 then 
begin 
SetCtlValueCC.FrequencyScrollbar, newValue); 
1f newValue © 128 then 
NumToStr ingCnewValue, FreqText) 


else 
FreqText := 'Rest'; 
InvalRectCFreqRect); 
end; 
end; 
2 
begin 


MyDoc^ .amp[GetCt1Value(C_NoteScro] Ibar ) 
+ NewPosition] := newValue; 
1f NewPosition = 0 then 


begin 
SetCtlValueCC_AmplitudeScrollbar, newValue); 
NumToString(newValue, AmpText); 
InvalRectCAmpRect); 
end; 
end, 


begin 
MyDoc* .dur [GetCt1ValueCC NoteScrollbar) 
+ NewPosition] := newValue; 
1f NewPosition = 0 then 
begin 
SetCtlValueCC. DurationScrollbar, 


3 


newValue); 
NumToStringCnewValue, DurText); 
InvalRect(DurRect); 
end; 
end; 


begin 
MyDoc^ .timbre[GetCtlValueCC NoteScrollbar) + NewPosition] := 
newValue; 


4 


1f NewPosition = 0 then 
begin 
SetCtlValueCC.TimbreScrollbar, 


newValue); 
NumToString(newValue, TimbreText); 
InvalRect(TimbreRect); 
end; 
end; 
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end; ( of Case) 
SetRect(TempRect, (NewPosition * 10 + 
6), 6, (NewPosition х 10 + 5) + 9, 259); 
InvalRect(TempRect); 
end; (end of still in NotePallete) 
BeginUpdateCMyWindow); 
Update. Unt i tledCMyWindow); 
EndUpdate (MyW indow); 
GetMouse(myP і); 
until not (StillDown); 
(End for 1f (MyWindow=whichW indow )) 
(End for if (MgWindowOni 12) 
(End of procedure) 


end; 
end; 


end; 
end. (End of unit) 


Listing: HandleTheMenus.pas 
unit HandleTheMenus; 
interface 
uses 
PrintTraps, Message, save changes, About, Untitled, Sound, 
MyGlobals, MyFileStuff, MyPrintStuff; 
procedure AdjustMenus; 
procedure Hendle.My.Menu (var doneFlag: boolean; theMenu, 
theItem: integer); (Handle menu selection) 
implementation 
procedure AdjustMenus; 
begin 
if (FrontWindow <> MyWindow) then 
begin (Something up there) 
DisableItem(M_Extend, 0); 
EnableItemC(M.Edit, 0); 
DisableItemCM.File, МІ Ореп); 
Disableltem(M_File, МІ Мем); 
Disableltem(M_File, MI. Close); 
DisableItemCM.File, МІ Save2; 
DisableItemCM.File, MI.Save. А5); 
DisebleItemCM File, MI Page Setup); 
DisableItem(M.File, MI_Print); 
end 
else if MyWindow © nil then 
begin (My Window up there) 
EnableItem(M. Extend, 0); 
DisableItemCM Edit, 0); 
DisebleItem(M. File, MI_Open); 
DisableItem(M File, MI. New); 
EnableItem(M. File, МІ Close); 
EnableItem(M.File, MI Save); 
EnableItem(M. File, МІ. Save. As); 
EnableItem(M. File, MI_Page_Setup); 
EnableItemC(M.File, MI_Print); 
end 
else 
begin (nothing up there) 
VolRefNum := 8; (no need to save any changes) 
DisableItemCM. Extend, 0); 
DisableItemCM. Edit, 0); 
EnableItemC(M. File, MI. Open); 
EnableItemC(M.File, MI New); 
Disableltem(M_File, МІ. Close); 
Disableltem(M_File, MI Save); 
Disableltem(M_File, MI_Save_As); 
Disableltem(M_File, MI_Page_Setup); 
Disableltem(M_File, MI_Print); 
end; 
end; 
procedure Handle_My_Menu; 
var 
DNA: integer; 
BoolHolder: boolean; 
DAName, title: Str255; 
SavePort: GrafPtr; 
i, theValue: integer; 
begin (Start of procedure} 
case theMenu of (Do selected menu list) 
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L_Apple: 
begin 
case theltem of 
MI_About_Zoundz: 
begin 
D_About; 


end; 
otherwise (Handle the DAs) 
begin 
GetPort(SavePort); 


GetItemCAppleMenu, theItem, DAName); 


DNA := OpenDeskAccCDAName ); 
SetPort(SavePort2; 
end; 
end; (End of item case) 
end; (End for Apple Menu list) 
LFile: 
begin 
case theItem of 
MI_New: 
begin 
InitUntitled; 
Open_Untitled; 
dirty := false; 
end; 
MI_Open: 
begin 
do0pen; 
1f VolRefNum <> 0 then 
begin 
Open_Untitled; 
SetWTitleCMyWindow, FileName); 
dirty := false; 
end; 
end; 
MI_Close: 
begin 
if dirty then 
begin (need saving) 
GetWTitleCMyWindow, title); 
ParamText(title, '', ‘’, “4%; 
theValue := D_save_changes; 
if (theValue = I Yes) then 


begin (wants to save changes) 


1f VolRefNum = 2 then 
doSaveAs 

else 
doSave; 

if VolRefNum © 0 then 


Close Untitled(MyWindow); 


end 
else if theValue = I_No then 
Close-UntitledCMyWindow); 
end (of needing saved) 
else (no need to save) 
Close .Untitled(MyWindow); 
end; 
MI_Save: 
begin 
if VolRefNum = 0 then 
doSaveAs 
else 
doSave; 
if VolRefNum © Ø then 
dirty := false; 
end; 
MI_Save_As: 
begin 
doSaveAs; 
1f VolRefNum <> 0 then 
dirty := false; 
end; 
MI. Page Setup: 
begin 
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doSetUp; 
end; 
MI.Print: 
begin 
doPr int ; 
end; 
MI_Quit: 
begin 
if (MyWindow © nil) and dirty then 
begin (need saving) 
GetWTitle(MuWindow, title); 
Paramlext(title, ‘’, ””, “49; 
theValue := D_save_ changes; 
case theValue of 
I_Yes: 
begin 
1f VolRefNum = 0 then 
doSaveAs 
else 
doSave ; 
1f VolRefNum <> 2 then 
doneFlag := TRUE; 
end; (of Yes) 
I-No: 
doneFlag := True; 
otherwise 


7 
end; (of case) 
end (of needing saved) 
else (no need to save) 
doneFlag := TRUE; 
end; 
otherwise 


end; (of item list) 
end; (of File Menu List ) 
L_Edit: 
begin 


BoolHolder := SustemEdit(theItem - 1); (DA Editing) 


end; 
L_Extend: 
begin 
case theltem of (Handle extending values) 
MI_Frequencu: 
begin 

theValue := MyDoc^.freql(NoteIndex]; 
for i := MyDoc* StartValue to 


MyDoc^ .EndValue do 


Муос“ .freq[il := theValue; 
end; (of Frequency) 
MI.Amplitude: 
begin 
theValue :- MyDoc*.amp[NoteIndex]; 
for i := MyDoc* StartValue to 


MyDoc^ .EndValue do 


MyDoc^.amp[i] := theValue; 
end; (of Amplitude) 
MI Duration: 
begin 
theValue := MyDoc*.dur[NoteIndex]; 
for i := MyDoc* StartValue to 


MyDoc^ .EndValue do 


MyDoc^.dur[il := theValue; 
end; (of duration) 
MI_Timbre: 
begin 
theValue := MyDoc^.timbre[NoteIndex]; 
for i := MyDoc* StartValue to 


MyDoc^ .EndValue do 


MyDoc^.timbre[i] := theValue; 
end; (of timbre) 
otherwise 


end; ( of items in Extend Menu) 
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InvalRect(NotePallete); 
end; (of Extend Menu List) 
otherwise 


end; (End for the Menus) 


HiliteMenu(@); (Turn menu selection off) 
end; (End of procedure Handle_Mu_ Menu) 
end. (End of unit) 


Listing: Zoundz.pas 
program Zoundz; 
(Program name: Zoundz.Pas ) 
(Function: Allows creation of ‘snd ' resource 10=9000. ) 
(Historu: 4/17/89 Original bu Prototuper. ) 
(Modified: 5/1/89 bu Kirk Chase) 
uses 
PrintTraps, Message, save_changes, About, Untitled, 
InitTheMenus, HandleTheMenus, Sound, MuGlobals, MyFileStuff, 
MyPr intS tuff ; 
const 
WNETrapNum = $60; 
UnImplTrapNum = $9F; 
MultiEvt = 15; 


bit = 31; 
GrayRgnLowMemGlobal = $9EE; 
var (Main variables) 


myEvent: EventRecord; 

ResumePeek: WindowPeek; 

theWorld: SysEnvRec; 

doneFlag, DoIt, WNE, sysResult: boolean; 
code, theValue: integer; 

whichWindow: WindowPtr; 

dragRect: Rect; 

mResult: longint; 

theMenu, theItem: integer; 

chCode: integer; 

ch: char; 

myPt: Point; 

title: str255; 

nDocs, message, index, sleep: integer; 
theFile: AppFile; 

theErr: OSErr; 


procedure InitMac; (initializes Macintosh) 


begin 
MoreMasters; (This reserves space for more handles) 
InitGraf (@thePort); (Quickdraw Init) 
InitFonts; (Font manager init) 
InitWindows; (Window manager init) 
InitMenus; (Menu manager init) 
TEInit; (Text edit init) 
InitDialogs(nil); (Dialog manager) 


FlushEvents(everyEvent, 0); (Clear out all events) 


InitCursor; (Make an arrow cursor) 
end, 
procedure InitApp; (initialize application) 
var 
tempHandle: handle; 
begin 
doneFlag := FALSE; (0o not exit program yet) 
Init_My_Menus; (Initialize menu bar} 


MyDoc := DocPtr(NewPtr(sizeof(DocRec))); (get doc) 
ThePrintRec := nil; (print initialization} 

Рг0реп; 

tempHandle := NewHandle(sizeof (TPrint)); 
ThePrintRec := THPrint(tempHandle); 
PrintDefault(ThePrintRec); 

PageRect := ThePrintRec^^ .prinfo.rpage; 

PrClose; 

dragRect := screenbits.bounds; (Get drag area) 


SetRect(dragRect, dragRect.Left + 18, dragRect.Top + 25, 


dragRect.Right - 10, dragRect.Bottom - 10); 
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SetRect(NotePallete, 5, 5, 235, 260); (set rectangles) 

SetRect(EndRect, 345, 235, 370, 250); 

SetRect(StartRect, 345, 195, 370, 210); 

SetRect(TimbreRect, 465, 85, 490, 100); 

setRect(DurRect, 465, 65, 490, 80); 

SetRectCAmpRect, 465, 45, 490, 60); 

SetRect(FreqRect, 465, 25, 500, 40); 

SetRect(NoteRect, 420, 5, 445, 20); 

Dirty := false; 

theWatch := GetCursor(watchCursor); 

HLockCHandleCtheWatch2); 

theSquare := GetCursor(crossCursor ); 

HLockCHandleCtheSquare)); 

theErr := SysEnvirons(1, theWorld); 

if (theWorld.machineType >= 0) and 
(NGetTrapAddressCWNETrapNum, ToolTrap) = 
NGetTrapAddressCUnImplTrapNum, ToolTrap)) then 


WNE := false 
else 

WNE := true; 
sleep := 10; 


end; 


procedure AdjustCursor; (set cursor) 
begin 
if (FrontWindow = MyWindow) and (MyWindow © nil) then 
begin (our window in front) 
Ge tMouse (myP t ); 
if PtInRect(myPt, NotePallete) then 
SetCursor(theSquare^^) (over note pallete) 
else 
SetCursorCarrow); (over other stuff) 
end 
else 
SetCursor Carrow); 
end; 


begin (Start of main body} 
InitMac; 
InitApp; 
(finder startup} 
CountAppFilesCmessage, nDocs); 
1f nDocs = 0 then 
begin (no files to open} 


Init.Untitled; (Initialize the window routines) 
Open.Untitled; (Open window routines at program start) 
end 
else 


begin (files to print or open) 
1f message = appPrint then 
begin (print docs) 
for index := 1 to nDocs do 
begin (Loop through docs) 
GetAppFilesCindex, theFile); 
if theFile.fType = '770C' then 
begin (my file) 
VolRefNum := theFile.vRefNum; 
FileName := theFile.fName; 
OpenFile; 
if VolRefNum © Ø then 
begin 
Open_Untitled; 
SetNTitleCMyWindow, FileName); 
doPrint; 
Close-UntitledCMyWindow2; 
end; 
end; 
ClrAppFilesCindex2; 
end; (Loop through docs) 
doneFlag := true; (quit when done) 
end (print docs) 
else 
begin (open first file, can’t open multiple) 
GetAppFilesC1, theFile); 
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repeat 


1f theFile.fType = '7ZDC' then 
begin 
VolRefNum := theFile.vRefNum; 
FileName := theFile.fName; 
OpenFile; 
1f VolRefNum = 0 then 
begin 
Init.Untitled; (Init window routines) 
FileName := ‘Untitled’; 
end; 
Open_Untitled; (Open window routines) 
SetWTitleCMyWindow, FileName); 
for index := 1 to nDocs do 
ClrAppF i lesC index); 
end; 
end; 
end; 


(Start of main event loop} 
AdjustMenus; 
AdjustCursor; 
if WNE then 
DoIt := WaitNextEventCeveryEvent, myEvent, sleep, nil) 
else 
begin 
SystemTask; 
DoIt := GetNextEventCeveryEvent, myEvent); 
end; 
if DoIt then(If event then...) 
begin (Start handling the event) 
code :- FindWindow(myEvent.where, whichWindow); 
case myEvent.what of (Decide type of event) 
MouseDown: (Mouse button pressed) 


begin 
if (code = inMenuBar) then 
begin 
mResult := MenuSelect(myEvent Where); 
theMenu := HiWord(mResult); 


theItem := LoWord(mResult); 
Handle.My.MenuCdoneFlag, theMenu, theItem); 
end; (End of inMenuBar) 
if (code = InDrag) then 


begin 
DragWindow(whichWindow, myEvent.where, dragRect); 
end; 
1f (code = inGoAway) then 
begin 
1f TrackGoAwayCwhichWindow, myEvent.where) then 
begin 
if dirty then 
begin (need saving) 
GetWTitleCMyWindow, title); 
Paramlext(title, ‘’, '', “42; 
theValue := D_save_changes; 
1f CtheValue = I Yes) then 
begin (wants to save changes) 
1f VolRefNum = 0 then 
doSaveAs 
else 
doSave; 
1f VolRefNum © 0 then 
Close.UntitledCMyWindow); 
end 
else if theValue = I. No then 
Close.Untitled(MgWindow); 
end (of needing saved} 
else (no need to save) 
Close_Unt itled(MyWindow); 


end; 
end; (End of InGoAway) 
if (code = inContent) then 
begin 
if CwhichWindow O FrontWindow) then 
SelectWindow(whichWindow) 
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else 
begin 
setPor tCwhichWindow); 
Do_UntitledCmyEvent); 
end; 
end; (End of inContent) 
1f (code = inSusWindow) then 
SustemClick(muEvent, whichWindow); 
end; (End of MouseDown) 
KeyDown, AutoKey: (Handle key inputs) 
begin 
with myevent do 
begin 
chCode := BitAnd(message, CharCodeMask); 
ch := CHRCchCode); 
1f COdd(modifiers div CmdKey)) then 


begin 
mResult := MenuKey(ch); 
theMenu := HiWord(mResult); 
theItem := LoWord(mResult); 


if (theMenu © 0) then 
Handle-My.MenuCdoneFlag, theMenu, theItem); 
end; 
end; 
end; (End for KeyDown, AutoKey) 
UpDateEvt: (Update event for a window) 
begin 
whichWindow := WindowPtr(myEvent .message?; 
BeginUpdateCwhichWindow); 
Update. Unt i tledCwh ichWindow2; 
EndUpdete(Cwh ichWindow); 
end; (End of UpDateEvt) 
DiskEvt: (Disk inserted event) 
begin 
if CHiWord(myevent.message) € noErr) then 
begin(due to unformatted diskette inserted) 
myEvent.where.h := 
(Cscreenbits.bounds.Right - screenbits.bounds.Left) div 2) - 
(304 div 2); 
myEvent.where.v : = 
((screenbits.bounds.Bottom - screenbits.bounds.Top) div 3) - 
(104 div 2); 
InitCursor; 
chCode :- DIBadMount(mgEvent . where, 
myevent.message); (Let the 05 handle the diskette) 
end; 
end; (End of DiskEvt) 
ActivateEvt: (Window activated event) 
begin 
whichWindow := WindowPtr(myevent .message); 
if odd(myEvent modif iers) then 
beg in Handle the activate) 
SelectWindow(whichWindow); 
end, 
end; (End of ActivateEvt) 
MultiEvt: 
begin 
1f Odd(myEvent message? then 
begin (resume event) 
if FrontWindow = MyWindow then 
begin 
SetPor t CMyW indow); 
InvalRectCMyWindow^ .portRect); 
end 
else if FrontWindow © nil then 
begin 
ResumePeek := WindowPeek(FrontWindow): 
1f ResumePeek^ .windowKind < 0 then 
begin 
myEvent.what := activateEvt; 
BitSetC@myEvent modifiers, bit@0); 
sysResult := 
SystemEvent(myEvent); 
end; 
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end; 
end (of resume event) 
else (suspend event) 


begin 
if FrontWindow = MyWindow then 
begin 
SetPor t (MyW indow); 
InvalRectCMyWindow^ .portRect); 
end 
else if FrontWindow © nil then 
begin 
ResumePeek := WindowPeek(FrontWindow); 


і? ResumePeek^ .windowK ind < Ø then 
begin 
myEvent.what := activateEvt; 
BitClrCémyEvent .modif iers, 6140); 


sysResult := 
SystemEvent(myEvent ); 
end; 
end; 
end; 
end; (of MultiEvt) 
otherwise 
end; (End of case) 
end; (end of GetNextEvent) 
until doneFlag; (End of the event loop) 
end. (End of the program) 
Listing: Zoundz.r 


ж RMaker resource file sources. 
X File: Zoundz.R 


Zoundz . RSRC 
29999999 


include CursIcons 
include AppStuf f 


Type DLOG 


,3 ;;Resource ID 
save changes ;;Dialog title 
58 120 188 365 ;;lop Left Bottom Right 
Visible NoGoAway ;;Visible GoAway 


1 ;;ProcID, dialog def ID 
3 ;;Refcon, reference value 
3 ;;ID of item list 
Tgpe DITL 
, 3 ;;Resource ID 
4 ;;Number of controls in list 


Button Enabled ;;Push button 
10 30 90 100 ;;lop Left Bottom Right 
Yes ; message 


Button Enabled 
100 158 128 220 
Cancel 


;,Push button 
;;Top Left Bottom Right 
j message 


Button Enabled ; Push button 
100 30 120 100 ;; Top Left Bottom Right 
No ; message 


StaticText 
10 30 55 220 


;,Static text 
Тор Left Bottom Right 


Save changes to “0? ; ¿message 
Tupe WIND 
‚1 ;;Resource ID 
Untitled ;;Window title 
490 


42 5 337 506 


InVisible GoAway 


4 
1 


Туре CNTL 


, 26 
Plau Sound 
120 245 160 
Visible 
0 
26 
010 


, 16 
Timbre 
255 395 270 
Visible 
1 
16 
011 


,15 
Duration 
235 395 250 
Visible 


, 14 
Amplitude 
215 395 230 
Visible 
] 
14 
011 


, 13 
Frequency 
195 395 210 
Visible 
1 
13 
011 


,20 
Timbre 
85 260 
Visible 
2 
20 
0 10 


, 19 
Duration 


490 


485 


485 


485 


485 


100 350 


65 260 80 350 


Visible 
2 

19 
010 


,18 
Amplitude 


45 260 60 350 


Visible 
2 

18 

0 10 


, M 
Frequency 


25 268 40 350 


;;Top Left Bottom Right 

;;Visible GoAway 
;;ProcID, Window def ID 
;,;Refcon, reference value 


; Resource ID 
‚Те for a Button 
;;Top Left Bottom Right 
j; Initially visible 
;;ProcID (Control definition ID) 
;;RefCon (reference value) 
;;Min Max Value 


;;Resource ID 
;;litle for a Checkbox 
;;Top Left Bottom Right 
;;Initially visible 
;;ProcID (Control definition ID) 
¿;RefCon (reference value) 
;;Min Max Value 


;;Resource ID 
‚Те for a Checkbox 
;;lop Left Bottom Right 
;;Initially visible 
;;ProcID (Control definition ID) 
;;RefCon (reference value) 
;;Min Max Value 


;;Resource ID 
Те for a Checkbox 
;; Top Left Bottom Right 
jj Initially visible 
;;ProcID (Control definition ID) 
;;RefCon (reference value) 
;;Min Max Value 


;;Resource ID 
;;litle for a Checkbox 
;,Top Left Bottom Right 
jj Initially visible 
;;ProcID (Control definition ID) 
;;RefCon (reference value) 
;;Min Max Value 


;;Resource ID 
;;litle for a RadioButton 
;,lop Left Bottom Right 
j; Initially visible 
;;ProcID (Control definition ID) 
;;RefCon (reference value) 
;;Min Max Value 


;;Resource ID 
;;litle for a RadioButton 
;;Top Left Bottom Right 
j; Initially visible 
;;ProcID (Control definition ID) 
;;RefCon (reference value) 
;;Min Max Value 


;;Resource ID 
;; Title for a RadioButton 
;;Top Left Bottom Right 
jj Initially visible 
;;ProcID (Control definition ID) 
;;RefCon (reference value) 
;,Min Max Value 


; Resource ID 


;;litle for a RadioButton 
;;lop Left Bottom Right 
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Visible ¿;Initiallu visible 10 55 80 245 3; Top Left Bottom Right 
2 ;;ProcID (Control definition ID) “01007 11007210023 ; message 
17 ;;RefCon (reference value) 
011 ;,Min Max Value 
Button Enabled ; Push button 
,41 ;;Resource ID 90 140 110 200 ;,lop Left Bottom Right 
DurationScrollbar ;;litle for a Scrollbar OK ;,message 
65 360 81 460 ;,Top Left Bottom Right 
Visible jj Initially visible Type DLOG 
16 ;;ProcID (Control definition ID) 
41 ;;RefCon (reference value) ,2 ;,;Resource ID 
0 250 0 ;,Min Max Value About ;;Dialog title 
112 136 210 373 Тор Left Bottom Right 
, 8 j Resource ID Visible NoGoAwau ;;Visible GoAwau 
AmplitudeScrollbar ;;litle for а Scrollbar 1 ;;ProcID, dialog def ID 
45 360 61 460 Тор Left Bottom Right 2 ;;Refcon, reference value 
Visible ;;l1nitially visible 2 ;;ID of item list 
16 ;,ProcID (Control definition ID) 
40 ;;RefCon (reference value) Type DITL 
0 255 0 |Міп Max Value 
;,Resource ID 
‚ 39 ;;Resource ID 3 ;;Number of controls in list 
FrequencyScrollbar ;; Title for a Scrollbar 
25 360 41 460 ;,lop Left Bottom Right Button Enabled ; Push button 
Visible ;;initially visible 60 75 87 ;;lop Left Bottom Right 
16 ;;ProcID (Control definition ID) OK j message 
39 ;¿;RefCon (reference value) 
0 128 0 ;;Min Max Value StaticText ;,Static text 
10 35 25 205 ; Тор Left Bottom Right 
‚38 ;;Resource ID Zoundz 1.0 Bu Kirk Chase j message 
TimbreScrollbar Те for a Scrollbar 
85 360 101 460 Тор Left Bottom Right StaticText ;,Static text 
Visible ;, Initially visible 35 10 50 225 ;;lop Left Bottom Right 
16 ;;ProcID (Control definition ID) € 1989 Kirk Chase and MacTutor ;;теѕѕәде 
38 ;;RefCon (reference value) 
g 254 0 ;;Min Max Value Type MENU 
‚31 ;;Resource ID , 1001 ;;Resource ID 
EndScrollbar ;;litle for a Scrollbar \14 ;, MPPLE menu title 
255 258 271 370 ;;lop Left Bottom Right About Zoundz... jitem title 
Visible ;;Initially visible c= 7 
16 ;;ProcID (Control definition ID) 
31 ;;RefCon (reference value) , 1002 ;;Resource ID 
1 100 1 ;;Min Max Value File ;,menu title 
CNew/N jp, item title 
,21 j ¿Resource ID COpen.../0 ;;item title 
StertScrollbar ;;litle for a Scrollbar c hp 
215 250 231 370 ;,lop Left Bottom Right Close ;;item title 
Visible ;;lnitially visible Save /S ;;item title 
16 ;;ProcID (Control definition ID) Save As... ;;item title 
21 ¿;RefCon (reference value) (= 
1 106 1 ;;Min Max Value Page Setup... ;;ltem title 
Print... ;;item title 
, 12 ; ¿Resource ID (- 33 
NoteScrollbar Те for a Scrollbar Quit/Q ;;item title 
266 5 282 231 ;,lop Left Bottom Right 
Visible ;;Initially visible , 1003 ;;Resource ID 
16 ;;ProcID (Control definition ID) Edit ;,menu title 
12 ;;RefCon (reference value) Undo /Z ;;ltem title 
1 100 1 ;;Min Max Value C= E 
Cut/X jj item title 
Type ALRT Copy/C ;; item title 
Paste/V j, item title , 
‚4 ;;Resource ID 
15 124 210 385 Тор Left Bottom Right , 1004 
4 ;;ID of item list Extend 
CCCC . ;;stages of alert in hexadecimal Frequency 
Amplitude 
Type DITL Duration 
Timbre 
‚4 ;;Resource ID 
2 ;;Number of controls in list 
StaticText jj, Static text 
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Programmer s Forum 
Understanding Color Icons 


Understanding, Creating 
and Using Color Icons 
Steve and Patricia Sheets 

Traditional Quickdraw contains numerous data structures. 
Bit Images, BitMaps, Patterns, and Icons are all graphic concepts 
that a Macintosh programmer uses in order to manipulate Quick- 
draw. Mostof these graphic concepts are layered in construction. 
For example, in order to understand how to create and manipulate 
Icons, a Mac programmer needs to know about Bitmaps. 

The topic of this column is the Color Icon data structure. The 
same layered approach that is used in traditional Quickdraw is 
also used in Color Quickdraw. Thus in order to understand Color 
Icons, this article will explain about Pixel Images, Pixel Bitmaps, 
and Color Look-up tables. Once the Color Icon’s structure is 
defined, this article will discuss the simple usage of Color Icons 
in Menus and Dialogs. Finally, creating Color Icons using 
ResEdit templates will be covered. 


Bit Images and Bitmaps 

In Quickdraw, the basis of all graphic data structures is the 
Bit Image. The Bit Image is a portion of memory that represents 
an arbitrary black and white display. Each bit of the image 
represents a pixel of the display. If a Bit is set, the pixel is black. 
If it is unset, the pixel is white. The pixels аге laid out left to right, 
then top to bottom. The Pixel in the upper left corner is defined 
in Bit 1, the Pixel to the right of it is defined in Bit 2 and so on. 
Notice that a Bit Image has no built-in definition. There is no 
explanation of the horizontal or vertical dimensions of the image. 
Non-color Macintosh (Mac 128K, Mac 512K, Mac Plus, Mac 
SE) screens are represented as Bit Images. 

The Quickdraw Bitmap is the data structure that represents 
an exact black and white display. A Bitmap contains a pointer to 
the Bit Image, the row width of that Bit Image, and the coordi- 
nates of that Image. The coordinates of the Bit Image is defines 
as a boundary rectangle. The upper left coordinate of the 
rectangle is the first pixel of the Bitmap. In most cases, this is 
defined as 0,0. While it is easiest to work with Bitmaps laid out 
this way, the upper left coordinate could be any value. The row 
width defines the the number of pixels that are on one row of the 
Bit Image. This is given in Bytes of memory, not pixels. Also, 
the row width must be an even number of Bytes. Thus a BitMap 
that had 32 pixels in arow would have a byte with at least 4 bytes 
(8*4). Therow width could be larger, that would just mean some 
of the bits of the Image were not being used. For example, a 
Bitmap that had only 30 pixels in a row would still require a row 
width of 4 bytes. The 31st & 32nd bits would not be used. 


Bitmap = RECORD 
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Steve and Patricia Sheets 


E Herdon, VA 
System Volume 5, Number 10 
baseAddr: Ptr; 
rowBytes: Integer; 
bounds: Rect; 
END; 


Pix Images and PixMaps 

Color Quickdraw’s equivalent of a Bit Image is the Pixel 
Image. The Pixel Image is a portion of memory that represents 
a display, possibly a color display. Each Pixel on the display is 
represented by one or more bits in the memory. The number of 
bits that is required for a single pixel is called the depth of the 
Image. Pixel Images are similar to Bit Images in that the size and 
row width of a Pixel Image is not defined. Also undefined is the 
depth of the image, the exact lay out of the bits in memory, and 
the conversion of the bits of a pixel to colors. All these values are 
defined in a Pixel Map. 

The Pixel Map is Color Quickdraw’s equivalent of a Bit 
Map. Like a Bitmap, it contains a pointer to the Image (Pixel in 
this case), the row width (in bytes) of the Image, and the 
dimensions of the rectangle. However the Pixel Map is more 
complicated than that. 


PixelMap = RECORD 
baseAddr: Ptr; 


rowBytes: Integer; 
bounds: Rect; 
pmVersion: Integer; 
peckType: Integer; 
packSize: LongInt; 
hRex: Fixed; 

vRes: Fixed; 


pixelType: Integer; 
pixelSize: Integer; 
cmpCount: Integer; 
cmpSize: Integer; 

planeBytes:LongInt; 
pmTeble: CTabHandle; 
pmReserved:LongInt ; 


END; 
PixMapPtr s^PixMap; 
PixelMapHendle = “PixmapPtr; 


A PixMap is usually manipulated as a handle. Most of the 
data structures and routines that work with PixMaps, use or pass 
handles to the PixMap. For this reason, the 3 high bits of the row 
width field are used as flags. The high bit of the row width field 
must be set (1). This indicates that this data structure is a PixMap, 
not a BitMap. The next two bits are reserved for future use. For 
now, they must be unset (0). 

Beyond the three normal Bitmap variables, the PixMap has 
twelve other variables. The pmVersion field contains the version 
number of Color Quickdraw. Currently this is set to 0. The 
packType field is used to define the Packing Algorithm that the 
PixMap uses on the bits. Again, this is normally set to 0 since, 
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as of now, Color Quickdraw does not support a PixMap packing 
algorithm. The packSize field contains the number of bytes of the 
packed image. It is set to 0 if no packing algorithm is used. The 
hRes and vRes fields contain the horizontal and vertical resolu- 
tion of the PixMap in pixels per inch. Currently all Mac screens 
are 72 DPI, thus the hRes and vRes settings of the Pixmap are 72. 

The next few fields define the exact layout of the bits in the 
PixMap’s Pixel Image. The pixelType field defines the format. 
PixelType should be set to 0 to indicate Chunky. A value of 1 
indicates ““Chunky/Planar” format and a value of 2 indicates 
“Planar”. The first and most important format is the “Chunky” 
format. In a Chunky Pixel Image, all of a row's pixels are stored 
consecutively. Thus for a Pixel Image with the depth of 4, the 
first 4 bits of memory represent the first Pixel. 

Originally, Chunky format was the only format that Color 
Quickdraw could use; all Mac // video cards used “Chunky”. 
However, with the introduction of video cards with more than 8 
bits per pixel, the other formats were also used. The Planar and 
Chunky/Planar formats divide the Pixel Image in memory into 
separate sections. These sections, called planes, usually repre- 
sent different color components of a shade. For example, a 24 Bit 
card might divide the memory up into Red, Green and Blue 
portions, or components, of memory. Hopefully, this column 
will be discussing more about 32-Bit Quickdraw in the future. 
For this article, only Chunky Format will be explored. 

For Chunky Format, it is important to realize that for every 
pixelonthe screen there is a group of consecutive bits in memory. 
This group of bits contains an integer value, representing the 
color of the pixel being displayed. For example, a PixMap with 
a depth of 4 would have 4 bits for every pixel in the image. Since 
4 bits can contain 16 distinct integer values (0 thru 15), that 
PixMap could contain 16 different colors at one time. A 8 bit 
PixMap could contain up to 256 distinct colors. 

The pixelSize field of the PixMap defines the depth of the 
PixMap and it's Pixel Image. The pixelSize must be in powers 
of 2 for Chunky format (ie. 1,2, 4, 8). The next field, cmpCount, 
defines the number of color components (planes). The cmpSize 
field contains the number of bits per each color component. The 
planeBytes field gives the offset from one color plane to the next. 
Since Chunky format has only 1 component, the cmpCount field 
is setto 1, the cmpSize field should match the pixelSize field, and 
the planeBytes field should be set to O (indicating no offset). 
Jumping ahead one field, the pmReserved field is exactly that: 
reserved for future expansion and currently set to 0. 

The last field of a PixMap to be explained is the pmTable 
field. So far, the layout and dimensions of the Pix Map have been 
defined. However, there has been no mention of how the value 
of a set of bits is converted into a RGB color. Such a conversion 
is defined in a Color Table data structure. The pmTable field 
contains a handle to a Color Table data structure. 


Color Tables 
So far in this article, the terms ‘screen’ and ‘PixMap display’ 
have been used interchangeably. This is not exactly correct. All 
video display devices are Graphic Devices. Graphic Devices 
have numerous data structures associated with them, including a 
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device driver, Color GrafPort, a Color Table and a PixMap. The 
Graphic Device’s PixMap is the entire viewable area of the 
screen. This is similar to the way traditional Quickdraw has a 
screenbit variable that is a Bitmap of the entire screen. Other 
PixMaps that contain portions of the screen must point to the 
same data as the Graphic Device’s PixMap and must share the 
same Color Table. However that Color Table is owned by the 
Graphic Device, not any PixMap. Offscreen PixMaps can also 
be created. These PixMaps would point to a different Pix Image 
than the Graphic Device. Each PixMap could have it’s own 
Color Table or share a Graphic Device’s Color Table. More will 
be discussed in the next article about the advantages of each 
method. For now, realize that there is a difference in layout 
between a Color Table owned by a PixMap and one owned by a 
Graphic Device. 

Both PixMaps or Graphic Devices use the Color Table data 
structure to convert the bit values of pixels into some RGB color. 
To do this, a Color Table contains a list of colors, defined in the 
Color Spec data structure. Each Color Spec contains a RGB color 
field, defined using the RGBColor data structure which specifies 
the Red, Green and Blue portions of the color. Each Color Spec 
also has a number associated with it. Thus if the Color Table has 
16 colors, there are 16 numbers associated with it. If the bits that 
are associated with a specific pixel of a PixelMap are equal to the 
number of some Color Spec, then that Pixel has that associated 
RGB value. If the PixMap was part of a Graphic Device, the 
display would show that RGB color on the Graphic Device. 
Where the number that is associated with each Color Spec comes 
from will be explained below. 

When some pixels of a PixMap are copied onto another 
PixMap, each pixel on the source PixMap is converted into the 
RGB value. Then the closest matching RGB value is found on 
the destination PixMap. The associated value is then placed in 
the destination PixMap in the correct bits. Thus Pix Maps having 
various depths and colors can be copied from one and another. 
While it makes things simpler and faster if the Pix Maps share the 
same Color Table, it is not necessary. Color Quickdraw calcu- 
lates the correct bit values for all the pixels even if they do not 
share the same Color Table. 


RGBColor = RECORD 
red: Integer; 
green: Integer; 
blue: Integer; 

END; 


ColorSpec - RECORD 
value: Integer; 
rgb: RGBColor; 


END; 
ColorTable = RECORD 
ctSeed: LongInt; 
ctFlags: Integer; 
ctSize: INTEGER; 
ctTable: ARRAY (0..01 OF ColorSpec; 
END; 
CTabPtr = *ColorTable; 


CTabHandle = “CTabPtr; 


493 


The Color Table data structure consists of a handle to a 
variable size record. The first field, the ctSeed field, is the version 
identifier number used internal by Color Quickdraw. It keeps 
track of changes to the Color Table. Everytime the Table is 
changed, the ctSeed needs to be reset using the Color Manager 
GetCTSeed function. If Color Quickdraw changes the Color 
Table, it will reset the field. If an application does the changes, 
it must reset the field. When creating PixMaps, this field is set 
to 0. 

The second field of the Color Table is the ctFlags field. As 
mentioned above, some Color Tables are owned by Graphic 
Devices, while others can be owned by simple offscreen 
PixMaps. If the PixMap owns the Color Table, this field must be 
set to 0. If the Graphic Device owns the PixMap, the high bit of 
the field will always be set. The rest of the bits of the field will 
be used as flags by the Graphic Device Manager. 

The next field of the PixMap is the ctSize field. It is the 
number of RGB colors that are defined in the Color Table. The 
number of colors equals the value of the field minus one, thus a 
setting of 1 indicates 2 Colors, while a setting of 255 indicates 
256 colors. For a Graphic Device, this number needs to be a 
power of 2. Fora PixMap, this number can be any positive value. 
Remember that the bit depth of the PixMap, not the ctSize field, 
defines the maximum number of colors for a Pixel Image. 

The last portion of the Color Table contains a variable size 
array of Color Spec data structures. The RGB field contains the 
exact Red, Green and Blue components of the Color Spec. The 
number that is associated with that Color Spec is dependent on 
who owns the Color Table. Graphic Devices use the position of 
the Color Spec (zero count) in order to find the number. Thus the 
first Color Spec would have the number 0, the next Color Spec 
would have the number 1 and so on. In that case, the value field 
of the Color Spec is used internally by the Color Device manager. 
Color Tables that are owned by PixMaps use the value field to 
determine what the number of the Color Spec is. Each value field 
of the Color Table should then have a unique number. While the 
contents of the value fields can be in any order (first Color Spec, 
value 9, next Color Spec, value 3, next one, value 23, and so on), 
it is recommended that PixMaps follow the Color Devices 
method of numbering the Color Specs (first Color Spec, value 0, 
next Color Spec, value 1, next one, value 2, and so on). This 
makes it easier to visualize the image. 

Graphic Devices have very special rules about the Color 
Tables associated with them. As mentioned above, the number 
of colors must be a power of 2, and match the bit depth of the 
Graphic Device. The first color must be white (RGB value 
$FFFF,$FFFF,$FFFF) and the last color must be black (RGB 
value $0,$0,$0). Color Tables used with PixMaps are much more 
unrestricted in their constructions. There can be any number of 
Color Specs and they may be in any order. Just remember that the 
PixMap that points to the Color Table can only use the first N 
number of colors where N is dependent on the depth of the Pix 
Image (depth 4, 16colors, depth 8,256). Itisa good rule of thumb 
to have the first Color Spec be white and the last one be black. 
Again, this makes it easier to visualize the image. 
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Icons and Color icons 

Now that an Image, a Bitmap, a Pixel Image and a PixMap 
have been discussed, traditional Icons and Color Icons can be 
explained. Under Quickdraw, an Icon is a Bit Image of a very 
specific size. The dimensions of an Icon are the always the same. 
An Icon is a 32 bit by 32 bit black and white image. It's Row 
width is 4 bytes. Since the dimensions are always the same, the 
Icon data structure consists of a handle to the Bit Image portion 
of the Icon. 

Under normal Quickdraw, there are two types of Icons; icons 
stored in ‘ICON’ resources and icons stored in ‘ICN#’ resources. 
The handle of a ‘ICON’ type Icon contains only the Bit Image. 
Since the Row Width is 4 bytes and the vertical size is 32, the size 
of such an Icon handle is 128 bytes. When an 'ICON' type Icon 
is drawn on the screen, the entire Bit Image is transferred (all 32 
by 32 pixels) to the screen. 

An ‘ICN#’ icon's handle contains the Bit Image of the Icon 
followed by the Bit Mask of the Image. Thus it is twice the size, 
or 256 bytes. If the Bit Image portion explains what is to be 
drawn, the Bit Mask portion explains where. Thus each pixel has 
2 bits associated with it, an Image bit and a Mask bit. When an 
‘ICN#’ type Icon is drawn on the screen, only the pixels of the Bit 
Image, whose corresponding Mask bits are set, are then trans- 
ferred to the screen. 

For example, imagine an “ІСМЯ” type of Icon consisting of 
a 10 by 10 frame. The Bit Image portion contains a hollow 
square. The pixels in the frame are set (black). The pixels of the 
outside of the frame and the inside of the frame are unset (white). 
The Bit Mask portion of the Icon contains a solid square. The 
pixels in the 10 by 10 square are all set, while only the pixels 
outside that 10 by 10 square are unset. When this Icon is drawn 
on the screen, only the pixels of the Bit Image that are set in the 
Bit Mask ( the ones in the 10 by 10 square) are copied. Thus if 
the Icon is copied onto a gray background, the frame would be 
black and the inside of the frame would be white. The idea that 
an Icon contains a Image and a Mask is an important one in 
understanding Color Icons. 

Given the understanding of all the other data structures, the 
Color Icon data structure is fairly simple. It contains a PixMap 
defining the Color Image, a Bitmap defining the Mask, another 
Bitmap defining the Black and White image, a Handle to the 
Color Image data and a variable size array of data containing the 
bitmap images. 


CIcon = RECORD 


iconPMap: PixMap; 

iconMask: Bitmap; 

iconBMap: BitMap; 

iconData: Handle; 

iconMaskData: ARRAY[0..0] of Integer; 
END; 
CIconPtr = ^ CIcon; 


CIconHandle =^ CIconPtr; 


The first thing to notice is that the Icon can be of any size, not 
just 32 by 32 pixels. The iconPMap field defines a PixMap of any 
given size, depth or color. Second, note that a Color Icon always 
contains a Mask, held in the iconMask field. When a Color Icon 


@ The Best of MacTutor, Vol. 5 


is drawn, only the color pixels in the PixMap which correspond 
to the set bits in the Mask Bit Image will be copied. Next, notice 
that the Pixmap will not be drawn on screens with a depth of 1 or 
2 (Black and White displaysor4 Color displays). In these cases, 
the BitMap defined in the iconBMap field would be drawn 
Instead. While the Pixel Image and the Bit Image do not need to 
look similar, it is better if they do. Both images share the same 
Mask. Finally, note that while the color Pixel Image data is stored 
as a handle in the iconData field, the Mask and Bitmap Images are 
stored at the end of the Color Icon data structure. Thus a Color 
Icon handle is a variable size handle, depending on the dimen- 
sions of the Mask and Bit Image. 


Color Icon Resource 

Now that the Color Icon data structure has been explored, 
creating Color Icons can be discussed. While Color Icons can be 
made with many methods, the most common опе is to use a Color 
Icon Resource. Color Quickdraw has a routine, GetCIcon, that 
creates a Pix Map (and associated Color Table and Pix Image) 
using aresource template. Color Icon resource use resource type 
‘cicn’. The important thing to realize is that the resource is used 
as information in the creation of a Color Icon. Once the Color 
Icon is created, the template is released by the call. This is 
different than other traditional Quickdraw resources (ie. ‘ICON’ 
or ‘ICN#’) where the resource is the entire data structure. The 
“сісп” resource is a merge of the various data structures and fields 
that the Color Icon data structure contains. Thus there are similar 
fields and values. The 'cicn' resource format and content is as 
follows: 


Name Date Type Use 
Icon PixMap Portion 
baseAddr Handle 0 
rowbytes Integer  rowbytes of PixMap 
bounds Rect boundary rectangle of PixMap 
pmVersion Integer 0 
packType Integer 0 
packSize Longint 0 
hRes Fixed 72 
vRes Fixed 72 
pixelType Integer O (Chunky) 
pixelSize Integer bits per pixel of PixMap 
cmpCount Integer 1 
cmpSize Integer bits per pixel of PixMap 
planeByte  LongInt 0 
pmTable Handle 0 
pmReserved LongInt 0 
Icon Mask Portion 
baseAddr Handle 0 
rowbytes Integer rowbytes of Mask 
bounds Rect boundary rectangle of Mask 
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Icon Bitmap Portion 
baseAddr Handle 0 
rowbytes Integer rowbytes of BitMap 
bounds Rect boundary rectangle of BitMap 
Icon Data Handle 0 
Mask Data Mask’s rowbytes * Mask’s vertical size 
Bitmap Data Bitmap's rowbytes * Bitmap's vertical 
size 
Color Table Portion 
ctSeed LongInt 0 
ctFlag Integer 0 
ctSize Integer Number of Color Specs - 1 
ctSpecs Number Specs*8 array of Color Specs 


PixMap Data PixMap’s rowbytes * PixMap's vertical 
size 


Many of the fields are place holders. As such, they are set 
to 0. Remember that Integers are 2 bytes in size, Handles are 4 
bytes, LongInt are 4 bytes, Fixed (real values) are 4 bytes and 
Rect (Rectangles) are 8 bytes (4 Integers). The rest of the field 
directly related to the Color Icon data structure. 


Color Icons in Menus and Dialogs 

The two most common usages of normal Icons are placing 
them in Menus and drawing them in Dialogs. In both cases, the 
‘ICON’ resources number is somehow defined in the Menu and 
Dialog. The Menu and Dialog Manager then displays the Icon. 

The method to place icons in the menu is slightly compli- 
cated. If a Menu Item is created using the GetMenu or Append- 
Menu procedures that contains a circumflex (^) followed by an 
ASCII character beyond 48, then the ASCII value of the character 
subtracted by 48 then added to 256 gives the resource number of 
the Icon to be displayed in that Menu Item. This strange 
numbering scheme means that a Menu Item with ‘41’ in it will 
display the Icon with the resource number of 257. ‘42’ will give 
resource number 258, while “А9” will give 256. Also the 
SetItemIcon procedure can be used to directly attach a Icon to a 
Menu Item. In that case, 256 must be added to the Icon number 
in the procedure to find the correct ICON resource number. Thus 
Icons that are displayed in the Menu must be in the range of 257 
to 512. 

To display Icons in Dialogs and Alerts, the Dialog Item List 
must contain an iconItem. That Item will contain the Display 
rectangle in local coordinates of the Dialog and the 2 byte 
resource ID. Any ICON resource number can be used. 

With the implementation of Color Quickdraw, changes to 
the Menu Manager and Dialog Manager have been added. Now, 
whenan Icon is referred to by a Menu or Dialog, first the resource 
number is calculated. Next, a Color Icon resource (‘cicn’) with 
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thatresourcenumberislooked for. Ifthatresource exists,a Color : ë 
Icon is created using it. That Color Icon will be displayed in the x шалы DU Steve SEP ал оге о ое 


Menu or Dialog. If a “сісп” resource with that resource number * revised cicn Resource Template 
does not exist, the ‘ICON’ resource with that number is looked : 
for and used. ; 
This method of using ‘cicn’ resource, when one exists, was | type ‘cicn’ ( 
well thought out. Imagine a program is created that has Icons in 2. S rn T ез š ТҮК / š 
NOMINA : : integer = * ew pixMa a S 
the menu and in it’s dialogs. The program is designed to run оп | пех aay dian dei ы 
color апа non-color Macintoshes. For each Icon needed, ап integer = 8; /* Bitmap bounds */ 
ICON resource and a ‘cicn’ resource are created with the same eee i m | 
number. When Ше program runs on non-color Macintoshes, Ше үш: В 32: 
А ° ° А , 
‘ICON’ resource is loaded into the computer and displayed. integer = 0; /* pixMap vers number */ 
When the program is run on a color Macintosh, the ‘cicn’ ar z : m 52-2 о. ар T 
: ; ongint = 0; ize of packed pixel data 
resource is found and displayed. Color Icons can be added to a unsigned hex longint = 900480000; /* h. resolu- 
program without any source code changes. Some of the Colori- | tion (ppi) (fixed) */ 
zation programs available use this idea to add color to programs is oe pee a = $00480000; /* v. resolu- 
ion (ppi ixe 
already created. integer = Ø; — /* Pixel storage format */ 
integer = 4; /* * bits in pixel x/ 
Creating Color Icon Resources E 7 i i : 27 
5 ; integer = 4; its per fie 
| Тһе Color Icon resource structure isacomplex one. It is not longint = 0; /% Offset to next plane */ 
a fixed width structure. Many of the field sizes are dependent on longint = 0; /% Offset to color table*/ 
the settings of other fields. For this reason, most resource tools longint = 0; /% Reserved */ 
(ResEdit, RMaker) are not capable of easily manipulating the /* IconMask (bitMap) record */ 
resource structure. The only resource tool that can do this is fill long; /* Base address x/ 
MPW's Rez tool. While MPW does have a ‘cicn’ resource integer hes / : Row bytes af | ‚ 
template that works, it has a couple of faults. First of all, itis hard сай = 0° аннары ыз 4 
to imagine the image that the Color Icon is trying to create. integer = 32; 
Changing and editing the Color Icon is difficult. Secondly the integer = 32; 
template does not do a good job of deciphering the Color Table /x IconBMap (bitMap) record */ 
portion of the data structure. Lastly, many of the fields of the data fill long; /* Base address */ 
structure could be precalculated or predefined. integer = 4; / : Row bytes */ , 
To solve these problems, a modified 'cicn' resource tem- ee _ 6; Шы ды / 
plate has been created (see resource code example #1). First а integer = 32 i 
couple of assumptions must be made. The Color Icon that is to integer = 32; 


becreatedmustbe within a32 by 32 pixelsize. Since the standard 
size of the tradition Icon is 32 by 32, this is usually acceptable. 
Secondly, the depth of the Color Icon is 4 bits or 16 colors. For array [32] ( /* Mask Data */ 
most uses, 16 colors are enough. | unsigned binary longint; 

Given these rules, large portions of the resource data struc- 
ture can be precalculated. Many of the fields are preset, while array [32] ( /* BMap Date */ 
other variable size fields can be defined as a fixed size. More өле кеша уона 
importantly, the Pixel Image and Bit Images can be displayed in | 


longint = Ø;  /* Handle placeholder */ 


Hex and Binary, respectively, so thatan image can be more easily | /* PMapCTab */ 
à А > longint = 0; /*ctSeed */ 

seen. Examine resource code example #2. Five different Color integer = 0; /* transIndex x/ 
icons are displayed in a more viewable format. Resource code integer = $$Countof(ColorSpec) - 1; /*ctSize*/ 
example #2 also contains the resource code for an Alert that wide x о ( ТЕ T 

: А . А . ex integer; value 
displays the icons. Creating Color Icons this way is much easier unsigned integer; /*RGB: red 7 
than using (ће template provided by MPW! Code example #3 unsigned integer; /* green */ 
gives the Pascal and Resource source for a very simple demon- ). unsigned integer; /* blue */ 
stration application. The application, cicnFun, displays the : 
Color Icons in an Alert. With this, an user can quickly see the array [32] ( /*PMap Data х / 
Color Icons that were created. | hex string[161; 
Listing 81: Clcon.r Т 
/* 

* File CIcon.r Listing 82: cicnFunRes.r 
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/* 


* File cicnFunRes.r 


x 


* Created by Steve Sheets for MacTutor 
x 


* Resource source file for cicnFun application 
x 


жү 


#include “Турев.г” 
®include *CIcon.r"^ 


resource ‘ALRT’ (1000) ( 
(40, 180, 192, 460), 1000, 


( OK, visible, silent, OK, visible, silent, 
OK, visible, silent, OK, visible, silent ) ); 


resource 'DITL^ (1000) ( 


( (112, 110, 132, 170), Button ( enabled, 


(60, 20, 92, 52), Icon ( disabled, 


(60, 72, 92, 104), Icon ( disabled, 1001 $, 
(60, 124, 92, 156), Icon ( disabled, 


(60, 176, 92, 208), Icon ( disabled, 
(60, 228, 92, 260), Icon ( disabled, 


(20, 79, 40, 261), StaticText ( disabled, 


"Ѕапре Color Icons”) ) ); 


resource ‘cicn’ (1000, “cicn Sun”) ( 


( 0000000000000000 111110000000000000 , /* Mask */ 


*/ 


0b00000000000000 1 11110000000000000 , 
0000 1111000000 1111111000000 111100, 
0000011111000001111111000001111100, 
0200011111100111111111110011111100, 
0000011111111111111111111111111100, 
000000 1111111111111111111111111000, 
0000000 111111111111111111111110000, 
00000000 11111111111111111111100000, 
06000000 11111111111111111111100000, 
0500000 11111111111111111111111000, 
0600000 111111111111111111111110000, 
0600011111111111111111111111111100; 
0001111111111111111111111111111111, 
0601111111111111111111111111111111, 
0001111111111111111111111111111111, 
0601111111111111111111111111111111, 
0601111111111111111111111111111111, 
0000011111111111111111111111111100, 
0000000 111111111111111111111110000, 
0200000 111111111111111111111110000, 
00000000 11111111111111111111100000, 
00000000 11111111111111111111100000, 
0000000 111111111111111111111110000, 
050000 1111111111111111111111111000; 
0500011111111111111111111111111100; 
000011111100111111111110011111100, 
000001111100000 111111100000 1111100, 
00000 1111000000 1111111000006 111100, 
0b00000000000000 111110000000000000, 
0b00000000000000 111110000000000000, 


0500000000000000000000000000000000 ), 
00000000000000000 11100000000000000, /* B&W Icon 


0000000000000000 1000 10000000000000 , 
000001111000000 1 10 1011000000 111100, 
00000 100 1100000 100 100 100000 1100 100, 
00000 10 10110011100 1001110011010100, 
0000011010111100000000011110101100, 
000000 110 100000 111111100000 1011000, 
0000000 110100111111111110010110000, 
00000000 10001111111111111000 100000, 
00000000 10011111111111111100 100000, 
000000 110111111111111111110110000, 
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/*For ALRT & DITL resources */ 
/*For revised cicn resources */ 


0000000 1001111001111100111100 10000, 
0500011101111111011101111111011100, 
0000 110001111111111111111111000 110; 
00 100000 111110011111001111 1000001, 
bø 1011101111100 111110011111011101, 
00 100000 111111111111111111 1900001, 
0500 110001111111110111111111000110, 


0Ы00011101111111111111111111011100, 
0500000 100 1111101111101111100 10000, 


0500000 110111111011101111110110009, 
05000000 100 11111100011111100 100000. 
05000000 1000 1111111111111000 100000, 
000000110 100 1111111111100 10110000), 
00000 1 10 100000 111111100000 10 11000, 
0600011010 1111000000000 111110 1100, 
0b000 10 10 110011100 102 11100 110 10 100, 
00000 100 1100000 100 100 100000 1100 100, 
00000 1111000000 110 1 11000000 111100; 
0000000000000000 1000 1000000000000 , 
00000000000000000 1 1 100000000000000 , 


0000000000000000000000000000000000 ), 


Üx0, 65535, 65535, 65535, /* Color Table */ 


0x1, 65535, 2998, 8638, 
0х2, 65535, 65535, 0, 
0x3, 65535, 17770, 2591, 
0х4, 0, 0, 


( $^00000000000000223220000000000000" , 


Image */ 


$"00000000000000234320000000000000" , 
$^00022222000000234320000000222200" 
$"00023332000002234322000002233200 " 
$^00023432200222234322220022343200" 
%%00022343222233333333322223432200"” 
400002234323334444444333234322000", 
$"00000223433444444444443343220000" , 
$^00000022334442222222444332200000" | 
$^00000023344422222222244433200000" 
$^00000223444222222222224443220000" , 
$ *000002334422 1 122222 1 122443320000" 
$ 00002234422222 1222 12222244322000" 
$°02222234422222222222222244322222", 
$^02333334422211222221122244333332", 
$^03444434422211222221122244344443" , 
$^02333334422222222222222244333332" 
$^0222223442222222 1222222244322222" , 
$^00002234422222222222222244322000" , 
$^0000023344222 122222 1222443320000", 
$^00000223444222 1222 12224443220000", 
$7000000233444222 11122244433200000" , 
$^00000022334442222222444332200000" 
$^00000223433444444444443343220000" | 
$^00002234323334444444333234322000" | 
$^00022343222233333333322223432200" , 
$^00023432200222234322220022343200" , 
$^00023322000002234322000002233200" | 
$^00022220000000234320000000222200 " , 
$"00000000000000234320000000000000" 
$^00000000000000223220000000000000" | 
$^00000000000000000000000000000000 '' 


resource ‘cicn’ (1001, "cicn Moof”) ( 


ы | 


( 0b11111111111111111111111111111111, 


0b11111111111111111111111111111111, 
06 11111111111111111111111111111111, 
0611111111111111111111111111111111, 
0011111111111111111111111111111111, 
0011111111111111111111111111111111, 
0011111111111111111111111111111111, 
0611111111111111111111111111111111, 
0611111111111111111111111111111111, 
06 11111111111111111111111111111111, 


—————————M———————————— ——— 


/* Pix 


) ); 


/* Solid Mask 


497 


| 


0511111111111111111111111111111111, 
0611111111111111111111111111111111, 
0b11111111111111111111111111111111, 
0511111111111111111111111111111111, 
0011111111111111111111111111111111, 
0b11111111111111111111111111111111, 
0011111111111111111111111111111111, 
0b11111111111111111111111111111111, 
0611111111111111111111111111111111, 
0b11111111111111111111111111111111, 
0011111111111111111111111111111111, 
0511111111111111111111111111111111, 
0511111111111111111111111111111111, 
0611111111111111111111111111111111, 
0611111111111111111111111111111111, 
0611111111111111111111111111111111, 
0611111111111111111111111111111111, 
0611111111111111111111111111111111, 
0b11111111111111111111111111111111, 
0611111111111111111111111111111111, 
0611111111111111111111111111111111, 
0b11111111111111111111111111111111 ), 


$"00000949994900000000000000009000 " , 
$"00000900009900000000000000009900 " , 
$"000099030099200000000000000949900" , 
$"00090000000900000000000009944990" , 
%%00900000000099000000000009440900", 
%”00900009900009999999999994409000", 
$ 0009999 1900000048888888844090000", 
$"00001119900000044466664440090000" , 
$"00001990004440000444444000090000" , 
$"00001000096640000000000000090000" , 
$"00000000098640000000000000090000 " , 
%”00000000096640000000000000090000", 
%”00000000094499999999999900090000", 
$"00000000290090000000000900099222" , 
$"00000021290092001000000990092222" , 
$*00000022790092727272222290097272", 
$"02221222990091121125555990091122" , 
$*22272229909975577555559909997222", 
$^2727222299227555555555599955 7555", 
%”22712222222222222222555555555555", 
%”22222222222222222221555555555555", 
$"22122112222222222221225555555555", 
$^22121222121222221221212225555555" , 
$^22112222211222222121122225555555" , 
$ “22722222227 722222277222225555555" ) ); 


— 


0b00000000000000000000000000000000, 
0b00000000000000000000000000000000, 
0000000000000000000000000000000000 , 
0500000000000000000000000000000000, 
0200000000000000000000000000000000, 


resource “сісп” (1002, “cicn Robbie”) ( 
( 0600000000000000111111110000000000, 


0200000000000000000000000000000000, 
0000000 111011100000000000000000000, 
0000000 101110 10000000000000000 1000, 
0200000 10000 110000000000000000 1100, 
020000 110 100 11000000000000000 10 100, 
00000 10000000 10000000000000 1100 100, 
0200 1000000000 1100000000000 1000 100, 
0000 10000 110000 111111111111000 1000, 
00000111101000000011111111000 10000, 
000000000 11000000000 111100000 10000, 
0000000 1100 100000000000000000 10000, 
00000000000 111000000000000000 10000, 
02000000000 111000000000000000 10000, 
00000000000 111000000000000000 10000, 
00000000000 100111111111111000 10000, 
02000000000 100 10000000000 1000 10000, 
00000000000 100 10000000000 1100 10000, 
02000000000 100 100000000000 100 10000, 
000000000 110 110000000000 1100 10000, 
000000000 110 1 10000000000 1 10 1110000, 
0000000000 112000000000000 1 1 1000000, 
0b00000000000000000000000000000000, 
0b00000000000000000000000000000000, 
0000000000000000000000000000000000, 
0000000000000000000000000000000000, 
0200000000000000000000000000000000, 


2000000000000000000000000000000000 ), 


0х0, 65535, 65535, 65535, 
0х1, 65535, 0, 0, 

0x2, 0, 65535, 0, 

0х3, Ø, 0, 65535, 

0х4, 57343, 57343, 57343, 
0х5, 9111, 49151, 8237, 
0x6, 32767, 32767, 32767, 
Øx7, 4158, 24575, 3251, 
0х8, 16383, 16383, 16383, 
0x9, 0, 0,0), 


0000000000000000111111110000000000, 
0000000000000000111111110000000000, 
0000000000000000111111110000000000, 
000000000000000011111111000000 1001, 
000000000000000011111111000000 1001, 
0000000000000000000 11000000000 1111, 
00000 11100000000 111111111000021111, 
0000000 110000001111111111100000 110, 
0000000 110000011100111011110001110, 
0000011111000111000111001111011100, 
0000000011101110000111000111111000, 
0000000001111100000111000011110000, 
0000000000 111000000 11100000 1100000, 
00000000000 1000000 1111110000000000, 
0000000000000000111111110000000000, 
0000000000000011111111111000000000, 
0000000000001111111111111000000000, 
0000000000111111111111111100000000, 
0000000011111111111111111100000000, 
0000000111111111111111111100000000, 
0000000011111111111111111110000000, 
000000 1011111111111111111110100000, 
0000011111111111111111111111110000, 
020000 1111111111111111111111100000, 
0000111111111111111111111111111000, 
0000011111111111111111111111110000, 
0000111111111111111111111111111000, 
000000 1111111111111111111111100000, 
0000011111111111111111111111110000, 
000000 1011111111111111111110100000, 
00000000 100 100 100 100 100 100 10000000 ), 


0000000000000000 1111111 10000000000, 
0000000000000000 1111111 10000000000, 
0000000000000000 100 1 100 10000000000, 
02000000020000000 100 1100 10000000000 , 
0000000000000000 11111111000000 1001, 
0р0000000000000011111111000000 1001, 
0000000000000000000110000000001111, 


( %”00000000000000000000000000000000”, 
%%”00000000000000000000000000000000”, 
$^00000000000000000000000000000000 " , 
$^00000000000000000000000000000000 " , 
$"00000000000000000000000000000000 ' , 
$^00000000000000000000000000000000 ` , 
%%00000999099900000000000000000000”, 


00000 11100000000111111111000001111, 
0000000 110000001111111111100000 110, 
0000000 110000011100111011110001110, 
000011111000 111000 111001111011100, 
0000000 11101110000 111000111111000, 
00000000 1111100000 1110000 11110000, 
0000000000 111000000 11100000 1100000, 
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0b00000000010000001111110000000000, 
0b00000000000000111111110000000000, 
0b00000000000011111111111000000000, 
0b00000000001111111111111000000000, 
0500000000 111111111111111100090000, 
0000000011111111111111111100000000, 
0200000 111111111111111111100000000, 
00000000 100 100 100 100 100 100 10000000, 
000000 1011111111111111111110100000, 
0500011111111111111111111111110000, 
000000 1111101111101111101111100000, 
0200111111101111101111101111111000, 
02000 111100000 100000 100000 11110000, 
0000111111101111101111101111111000, 
020000 1111101111101111101111100000, 
0000011111111111111111111111110000, 
050000 1011111111111111111110100000, 
0b 100 100 100 100 100 100 10000000 ), 


0х0, 65535, 65535, 65535, 
0х1, 65535, Ø, Ø, 

0х2, 0, 65535, 0, 

0х3, Ø, Ø, 65535, 

0х4, 49151, 48660, 48660, 
0х5, 32767, 32767, 32767, 
0x6, 24575, 24575, 24575, 
0x7, 0, 0, 0 ), 


$^00000000000000111111110000000000 " , 
$^00000000000000666666660000000000 | 
$^000000000000006 1166 1160000000000", 
$"000000000000006 1166 1160000000000" , 
$"00000000000000666666660000007001' 
$^00000000000000666666660000007001" | 
$^00000000000000000170000000007111" 
$^00011100000000444444444000004444" 
$^00000140000004444444444400000440" 
$^00000140000044440444044440004440" | 
%”00077744000444400444004444044400" 
$^00000044404444000444000444444400" , 
$^00000004444400000444000044444000" , 
$^00000000444000000444000004400000" 
$00000000040000004454440000000000" , 
$^00000000000000444555540000000000" 
$"00000000000044455555544000000000" 
$^00000000004445555555554000000000 " 
$^00000000444555555555554400000000" , 
$^00000044455555555555555400000000" , 
$^00000444444444444444444400000000" 
$^00000030030030030030030030000000 "| 
$^00003033333333333333333330300000 " ` 
$^00033333333333333333333333330000"" , 
$“90003333323333323333323333300000", 
$^00333333323333323333323333333000 " , 
$"00033332222232222232222233330000"' 
$"00333333323333323333323333333000" 
$^00003333323333323333323333300000 " 
$^00033333333333333333333333330000" | 
$"00003033333333333333333330300000 


$^00000030030030030030030030000000 FJ; 


resource ‘cicn’ (1003, “cicn Flag”) ( 


( 0000000000000000000000000000000000 
0:00000000000000000000000000000000 , 
0000000000000000000000000000000000 , 
0b00000000000000000000000000000000 , 
0000000000000000000000000000000000 , 
000000 1100000000000000000000000000, 
020000 1100000000000000000000000000, 
000000 1100000000000000000000000000, 
000000 1111111111111111111111111000, 
020000 1111111111111111111111111000, 
000000 1111111111111111111111111000, 
050000 1111111111111111111111111000, 
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000000 1111111111111111111111111000, 
000000 1111111111111111111111111000, 
00000 1111111111111111111111111000, 
050000 1111111111111111111111111000, 
000000 1111111111111111111111111000, 
000000 1111111111111111111111111000, 
000000 1111111111111111111111111000, 
000000 1111111111111111111111111000, 
000000 1111111111111111111111111000, 
020000 1100000000000000000000000000 , 
0b0000 1100000000000000000000000000 , 
000000 1100000000000000000000000000, 
000000 1100000000000000000000000000, 
000000 1100000000000000000000000000, 
000000 1100000000000000000000000000 , 
000000 1100000000000000000000000000 , 
000000 1100000000000000000000000000 , 
000000 1100000000000000000000000000 , 
020000 1100000000000000000000000000 , 


000000 1100000000000000000000000000 ), 


0000000000000000000000000000000000, 
йь00000000000000000000000000000000” 
0b00000000000000000000000000000000 , 
0000000000000000000000000000000000 , 
0000000000000000000000000000000000 , 
000000 1100000000000000000000000000 , 
000000 1100000000000000000000000000 , 
000000 1100000000000000000000000000, 
000000 1111111111111111111111111000, 
000000 1111011011011000000000000000, 
000000 1110110110111111111111111000, 
050000111110110110 1000000000000000 , 
060000 1111011011011111111111111000) 
000000 1110110110111000000000000000 
060009 1111111111111111111111111000, 
000000 1 100000000000000000000000000 , 
050000 1111111111111111111111111000, 
050000 1100000000000000000000000000 , 
060000 1111111111111111111111111000, 
00000 1 100000000000000000000000000 , 
060000 1111111111111111111111111000, 
000000 1100000000000000000000000000 , 
000000 1 100000000000000000000000000 
000000 1 100000000000000000000000000 
00000 1100000000000000000000000000 , 
000000 1100000000000000000000000000 , 
000000 1100000000000000000000000000, 
000000 1100000000000000000000000000, 
0b00001100000000000000000000000000 , 
000000 1100000000000000000000000000 , 
0b0000 1100000000000000000000000000 , 


020000 1100000000000000000000000000 ), 


Ox, 65535, 65535, 65535, 
0х1, 65535, 0, Ø, 

0х2, 65535, 65535, Ø, 
0х3, Ø, Ø, 65535 ), 


$^00000000000000000000000000000000 " , 
$^00000000000000000000000000000000" , 
$"00000000000000000000000000000000" , 
$"00000000000000000000000000000000" , 
$"000000000000000000000000000009000" 
$^00002200000000000000000000000000" , 
$^00002200000000000000000000000000* | 
$"00002200000000000000000000000000" , 
$"00002233333333333111111111111000", 
$^00002233033033033000000000000000 ", 
%”00002230330330333111111111111000", 
$^00002233303303303000000000000000" , 
$^00002233033033033111111111111000", 
$^00002230330330333000000000000000" | 
$^00002233333333333111111111111000"; 
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$"00002200000000000000000000000000 " , 
%”00002211111111111111111111111000", 
%”00002200000000000000000000000000", 
%”00002211111111111111111111111000", 
$"00002200000000000000000000000000 " , 
$"00002211111111111111111111111000" , 
$"00002200000000000000000000000000 " , 
$*00002200000000000000000000000000" , 
$"00002200000000000000000000000000 " , 
%”00002200000000000000000000000000", 
%”00002200000000000000000000000000", 
%”00002200000000000000000000000000", 
%”00002200000000000000000000000000”, 
$"00002200000000000000000000000000 " , 
%”00002200000000000000000000000000”", 
%”00002200000000000000000000000000”, 


%”00002200000000000000000000000000" ) ); 


resource ‘cicn’ (1004, “cicn Mac”) { 


( 0000000000000001111111111110000000, 
00000000000000 10000000000000000000, 
00000000000000 10000 111111000 100000, 
00000000000000 10000000000 100 100000, 
00000000000000 10000000000 100 100000, 
0000000 1000000 10000000000 100 100000, 
020000 11000000 10000000000 100 100000, 
020000 10000000 10000000000 100 100000, 
000 1100 1100000 10000000000 100 100000, 
00 100 1100 10000 10000000000 100 100000, 
00 1000000 10000 10001111111000 100000, 
Bb 100000000000 10000000000000 100000, 
Øb 100000000000 10000000000000 100000, 
020 100 10 1000000000000 1111100 100000, 
0000110 100000000000000000000 100000, 
0000000000 111111000000000000 100000, 
00000000 11000000000000000000000000, 
0000000 100000000011111111111110000, 
000000 10000000000000000000000 1000, 
0000000 1111100000000 1111111100100, 
0000000000000 1000000000 10 10 10 100 10, 
000000000000 1000000000000 10 10 1001, 
000000000000 1000000000000000000001, 
020000000000 1000000000000 111111110, 
0000000000000 110000000000000000000, 


~ 


000000000000 1000000000000000000001, 
000000000000 1000000000000111111110, 
9000000000000 110000000000000000000, 
000000000000000 1000000000000000000, 
000000000000000000 1 100000000000000 , 
00000000000000000 100 1000000000000 , 
0000000000000000 100 10 1000000000000 , 
000000000000000000 1000 100000000000, 
0000000000000000000000 100000000000, 


000000000000000000000 1000000000000 ), 


0х0, 65535, 65535, 65535, 
0х1, Ø, Ø, 65535, 

0х2, 65535, 65535, Ø, 
0х3, 0, 65535, 0, 

0х4, 65535, 0, 0, 

0х5, 0, 0,0), 


$"00000000000005555555555550000000" , 
%”00000000000050000000000000000000", 
%”00000000000050000222222000500000", 
$"00000000000050000000000200500000 " , 
$"00000000000050000000000200500000 " , 
$^00000300000050000000000200500000 " , 
%”00003300000050000000000200500000", 
$^00003000000050000000000200500000 " , 
$"03300330000050000000000200500000 " , 
%”30033003000050000000000200500000", 
$"30000003000050002222222000500000 " , 
%”30000000000050000000000000500000", 
%”30000000000050000000000000500000", 
%”03003030000000000005555500500000", 
%%00330300000000000000000000500000", 
$"00000000444444000000000000500000" , 
%”00000044000000000000000000000000", 
%%00000400000000055555555555550000", 
$^00000400000000000000000000005000 " , 
$^0000004444400000000 1111111109500" , 
$"000000000004000000000 10101010050", 
$^000000000004000000000000 10 10 1005", 
$"00000000004000000000000000000005 " , 
%”00000000004000000000000555555550", 


%”00000000000440000000000000000000", 


%”00000000000004000000000000000000", 
$"00000000000000005500000000009000 " , 
%%00000000000000050050000000000000", 
%”00000000000000500205000000000000", 
$^00000000000000002000500000000000 " , 
%”00000000000000000000500000000000", 
$"00000000000000000005000000000000" ) ); 


0b0000000000000 1000000000000000000, 
020000000000000000 1 100000000000000 , 
00000000000000000 100 10000000000000, 
0000000000000000 100 10 1000000000000, 
000000000000000000 1000 100000000000, 
0000000000000000000000 100000000000 , 
000000000000000000000 1000000000000 ), 
Listing 83: cicnFun Source 

( 0000000000000001111111111110000000, 
00000000000000 10000000000000000000 , (cicnFun - Sample Application to demonstrate Color Icons) 
00000000000000 100900 111111000 100000, ( Created by Steve Sheets for MacTutor) 
00000000000000 10000000000 100 100000, 


0000000000000 10000000000 100 100000, program cicnFun; 


0000000 1000000 10000000000 100 100000 , var 

020000 11000000 10000000000 100 100000 , N: INTEGER; 

020000 10000000 10000000000 100 100000, begin 

020 1100 1100000 10000000000 100 100000, InitCursor; 

06 1001100 10000 10000000000 100 100000, N := Мегі(1000, nil); 


Ob 1000000 10000 10001111111000 100000, end. 
Ob 100000000000 10000000000000 100000, 
Øb 100000000000 10000000000000 100000, 
020 100 10 1000000000090 1111100 100000, 
0000 110 100000000000000000000 100000, 
0000000000 111111000000000000 100000, 
02000000 11000000000000000000000000, 
0000000 1000000000 11111111111110000, 
0000000 10000000000000000000000 1000, 
00000000 1111100000000 1111111100100, = 
0b00000000000 1000000000 10 10 10 100 10, 22) 
0000000000000 1000000000000 10 10 1001, 


SEEPS 
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Pascal Procedures 
Writing INTIs in Pascal 


= Steve Kiene 


= ë Lincoln, NE 


Writing INITs in Pascal. 
Why Inits: Trap Patching, etc... 

INITs are pretty hot items these days. I have at least six in 
my System Folder and I know people that have fifteen or more. 
INITs do anything from making it easier to move through 
SFGetFiles (SFScrollINIT by Andy Hertzfeld) to creating large 
virtual desktops (SteppingOUT ID. INITs are used to customize 
the Macintosh. They are very simple to install and remove 
(dragging them into or out of the System Folder). 

The majority of INITs trap patches. Patch trapping is simply 
the rewriting of the Macintosh’s internal routines or the modifi- 
cation of these routines for special situations. This is done by 
using the traps GetTrapAddress,SetTrapAddress, NSetTrapAd- 
dress, and NGetTrapAddress. Usually the programmer calls 
GetTrapAddress and saves the address for later use; the program- 
mer then puts this address somewhere, usually in his/her code so 
that his/her code can check for the special situation, do 
whatever-taken that it is the special situation, and then call the 
Original trap address. All trap patches should call the original 
trap address; this allows traps to be patched more than one time 
and is the best bet for compatibility insurance. 

I would guess that 90% of all INITs are written in assembly. 
I'm sure they probably say that INITs are much easier to write in 
assembly. Well, it’s probably true, if you know assembly, but, if 
you don’t know assembly, I would say that it isn’t all that easy. 
This article, since it is in the Pascal section, demonstrates how to 
write an INIT in Pascal, includes full source to an INIT that 
allows the cursor to wrap around the screen, and gives a couple 
of hints on writing INITs in general. 


Having the INIT install our patch. 

INITs must load their code into the system heap so that the 
code will stay around as application’s are launched (the applica- 
tion heap is flushed every launch or return to the Finder). The 
INIT part of the code should put the trap patch or whatever code 
into the system heap. In CursorWrap, the included INIT, we 
create a pointer in the system heap that is four bytes greater than 
the size of our VBL task code; we then BlockMove the code into 
the pointer starting at the location of the pointer plus four. We 
store the pointer to our VBL task in the four bytes before our code 
so that we have easy access to it. The code is written in MPW 
Pascal, but should be easy to convert to any other development 
system. 


Unit CursorWrap; 
Interface 
Uses 
($LOAD MAC.Dump) 
MenTypes , QuickDraw, OS Intf , Tool intf ,PackIntf Script; 
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Procedure SetUpVBL ; 
Procedure Wrap; 
Implementation 
Procedure SetUpVBL; 
var 
theVBL : VBLTask; 
myQE Tem : QElemPtr; 
myErr : OSErr; 
SeveZone : THz; 
SizeNeeded : Longint; 
PatchPtr ; Ptr; 
theCode : Handle; 
thePtr : ^LongInt; 
dummyErr — : OSErr; 
Begin 


( * Get handle to our code *) 
theCode :=Get IResource( ‘INIT’, 1); 
( * Use the system's Heap * 
SaveZone : -GetZone; 
SetZone(SystemZone); 
( * Get size of our patch code and our QElem ptr * ) 
SizeNeeded : =SizeResource( theCode )-(LongInt(@Se tUpVBL )- 
Long Int( theCode*))+sizeof (QElem); 
ResrvMem(SizeNeeded); 
If MemError<>NoErr then 
begin 
( * If not enough room in system heap then get out * ) 
SysBeep( 1); 
SetZone(SaveZone); 
exit(SetUpVBL 5; 
end; 
( * Get new ptr for our code * ) 
PatchP tr :=NewPtr(SizeNeeded+4); 
( * blockmove our code in * ) 
BlockMoveC8Wrap,Pointer(Ord(PatchPtr)*4), SizeNeeded); 
( * get new ptr for our VBL task * ) 
myQE lem: -QElemPtr(NewPtr(Csizeof (QElem))); 
( * restore zone * ) 
Se tZone(SaveZone); 
( * put our vb] task ptr’s address into the ptr where our 
patch code will be * ) 
thePtr : Pointer CPatchPtr); 
thePtr^:-LongIntCmgQElem); 
( * set up VBL and install * ) 
with theVBL do 
begin 
qlype:=Ord(vType); 
vb lAddr :=Pointer(Ord(PatchPtr 244); 
vb 1Count :=6; 
vb IPhase : =0; 
end; 
myQE Тет“ .vb1QElem:=theVBL ; 
dummyErr :=VInstal1CmyQE lem); 
End; | 
( ) 
Procedure Wrap; 
xx 


This code allows the cursor to seemly wrap around the screen 
when the «Option? key is held down. It checks the low level 
interupt mouse location (mTemp) and if it is on one edge of 
the screen it moves it to the the other edge. It puts the new 
cursor cooridinate into mTemp and then puts $FF into cursor- 
New-this tells the cursor routines that the cursor has moved. 
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хх) 


const 
CurrentA5 = $904; 

var 
myQE lem : QElemPtr; 
theP tr : ^LongInt; 
CursorCoordPtr : ^Point; 
ChangedPtr : “Byte; 
changed : Boolean; 
theMap : KeyMap; 
currGDevice : GDHandle; 
mouseRect : Rect; 
myRectPtr : “Rect; 
myPtr, myPtr2 : ^longint; 
myRect : Rect; 

Begin 


( ж Get the keymap and check if option down; if is not then 
do not allow wrap * } 
GetKeys( theMap ); 
If theMap[58] then 
Begin 
( х set up ptr to low memory global of cursor location * ) 
CursorCoordP tr :=Pointer ($828); 
changed :=false, 
( * get rectangle of screen * ) 
currGDev ice:-GetGDevice; 
If currGDeviceO Nil then 
mouseRect : »currGDev ice^ ^ .gdRect 
else 
begin 
( * Use currentA5 to get offset to 
screenBits.bounds * ) 
myPtr:-pointerCCurrentA5); 
nyPtr2:-pointer(mgPtr^2; 
myRectPtr :-Pointer(myPtr2^-116); 
mouseRect : -myRectP tr^; 
end; 
InsetRect(mouseRect, 1, 1); 
( * check cursor location and change it if wrapping * ) 
With CursorCoordPtr^,mouseRect do 
Begin 
if v«stop then 
Begin 
v:=bottom- 1; 
changed: - true; 
End 
else if v»=bottom then 
Begin 
у:={ор+1; 
changed:=true; 
End; 
if h<=left then 
Begin 
h:=right- 1; 
changed: *true; 
End 
else if h»=right then 
Begin 
h:zleft*1; 
changed :=true; 
End; 
End; 
( * if we changed the cursor location then set the low 
memory global cursorNew * ) 
If changed then 
Begin 
changedPtr : -Pointer C$8CE); 
( * this tells the cursor drawing routines that the 
cursor is moved * ) 
chengedPtr^ :=$FF; 
End; 
End; 
( х get ptr to VBL taks from where we originally put it * ) 
thePtr :zPointerCOrdC8Wrap2-42; 
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( * reset the vblcount so that we are executed again * ) 
myQE Tem: -QElemPtrCthePtr^); 
mgQElem^.vblQElem.vblCount:76; 

End; 


End. 


Another Way 
There is another way to store variables. In our example INIT 
this would be the VBL pointer address. This way involves using 
a header file that is written in assembler. The header file does 
nothing but branch over instructions that take up space. The 
header would look something like the following in MPW assem- 
bly: 


Header MAIN EXPORT 
Header 1 

BRA.S 81 

DCL 0 

DCL 0 

ОС. Ø 
e1 

END 


This header would leave room for twelve bytes, three 
handles, or whatever. To use this you would have to link the 


Header.a.o in first and reference it in you pascal code. A little 
help: 


Procedure Header; EXTERNAL; (must be after Implementation ) 
myPtr:zPtrCOrdCGHeader2*2); ( myPtr points to the first byte 


of storage ) 


The above statement returns a pointer to the address of the 
header plus two bytes, so that we skip over the branch statement. 

You would use this type of code when you are writing a 
WDEF, CDEF, etc. and you want to have some type of commu- 
nication between your patches and your custom definition. We 
used this type of code when we wrote Tear-Off Menus and 
wanted our custom WDEF and MDEF to beable to access globals 
that our Menu and Window Manager traps used. 


Added tips for coping with problems. 

When writing INITS that are a little heavier than a “one trap 
patch' INIT or a simple VBL installation, then you are most 
likely going to run into problems with certain programs. Maybe 
it will be because the guys at Microsoft didn't quite follow all of 
the rules or perhaps it's some other reason. Regardless the 
problem, the answer is to not install when you know you are not 
compatible. The easiest way to do this is to try and load the 
resource type of the creator type (ie. MS WD for Microsoft Word) 


when the application is launched. 
theType : Get IResource( ‘MSWD’ ,@); 


If theTypeONil then ( the application exists М 
Since some users сап and do гепате their applications, опе 


can not just check for application names. Creator types should be 
unique (if they are registered with Apple) and no problems 
should be encountered this way. 


Good luck with your INITs. = 
Cad! 


Ыы?» 
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Pascal Workshop 
Dispatch Aliasing 


Dispatcher - An Application 
Aliasing and Launching Utility 

[Roger Horton is a Research Adjunct Assistant Professor at 
the Medical School of Wake Forest University, and a private 
consultant. He is currently in a masters degree program in 
computer science at the University of North Carolina, and has 
been programming in the Macintosh environment since 1985.] 

Recently, Icompleted a prototype of a database application 
for a dental office specializing in the treatment of facial pain. I 
choose 4th Dimension as the development environment due to its 
flexibility in reporting and for the ease with which external code 
routines can be incorporated. However, 4D has the habit of 
creating a large number of database files (for indexes, resources, 
data definitions, etc.), which can be very unsettling to the typical 
office user who happens to take a glimpse inside a 4D application 
folder. When the users reviewed the prototype they pointed this 
out, and requested that they be spared the intimidation of wonder- 
ing what all the files were for. At this point I began to consider 
the options for simplifying the process of installing and starting 
the application. 


Avoiding Confusion 

A frequent point of confusion for users of custom database 
applications is setting up and running the application. Something 
as simple as starting an application can be difficult for novice 
Mac users, if they have to traverse too many volumes and folders. 
Inothertext oriented operating systems, developers could rely on 
Shell scripts to simplify a user's interaction with the file system. 
On the Mac, macro programs have sprung up to fill this void. 
These can help, but often add more complexity than they elimi- 
nate. 

If the designer can personally walk each new user through 
the process of installation and startup, all is well. But all too often, 
the system is shipped to distant users who rely primarily on the 
documentation. As most of us have discovered, the knowledge 
level of the user varies widely, and the phone time spent in 
supporting these users, especially in the first weeks of use, can be 
considerable. | 

My goal was to keep the user out of the 4D application folder, 
with its many files, and allow a launch of the program from the 
Finder, using a single, easily identifiable icon. Finder alterna- 
tives were not considered, due to the user’s familiarity with the 
Finder and our desire to use Multifinder for coordination of other 
programs with the database application. I reviewed some macro 
processors that could potentially automate the launch process, 
but generally found that they were sensitive to the initial state of 
the desktop and were likely to be confusing to the average user. 
Since I hoped to simplify, instead of complicate, the training 
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process, I considered a custom solution. My initial thoughts 
centered around writing a small utility program that would take 
care of locating and launching the database application. I had 
previously written code to launch one application from another 
and so I set about considering how to use this code as a basis for 
a custom launcher application. I should note that normally I 
would have developed this type of utility program in C, but found 
that MPW version 2.0.2 C did not support the in-line launch code 
(but does in version 3.0). This caused me to turn to MPW Pascal, 
although I tried to develop the code for easy translation to C 
(avoiding booleans, ‘with’ statements, etc.). 


Help from the Finder 

My first intention was to build a launcher utility program that 
could be placed outside the 4D database folder. It would know (or 
could be shown) the location of the database folder, and could set 
up the Finder information record such that 4D would open the 
database after it was launched. This required storing the location 
of the 4D folder in the launcher program’s data or resource fork. 
This appeared to me to be a workable, but inflexible approach to 
the problem. There was also the problem of storing data in a 
resource fork, which Apple now discourages due to lack of access 
control to resource forks on networked systems. 

A second approach was to rely on some help from the Finder. 
Using information from the Desktop file, the Finder can launch 
an application when the user opens (or prints) one of its docu- 
ments. By taking advantage of this ability, I could create a 
dummy document and set its filetype to the filetype of the 
launcher program. It could then be placed anywhere in the file 
system (directly on the desktop, for example) and still initiate the 
launch program without knowing where the program file was. No 
file system paths need be remembered, but the launch program 
would always have to reside in the same folder as the application 
to be launched, and information about the target application 
would have to be imbedded in the program code. 


Generalizing the Dispatcher 

Any good computer scientist would realize that up to this 
point my approach was a very narrow solution to the problem, 
and lacked the generality we all strive for. So, I chose a solution 
that allowed for greater flexibility in setting the launch parame- 
ters. To do this, I relied on the dummy launch document to store 
the launch parameters, rather than embedding them in the pro- 
gram code or in the resource fork of the launch program. By doing 
so, the dummy documents (hereafter called launch settings files) 
become a sort of alias for the program they cause to be launched. 
They also store additional information needed for setting up the 
launch of the target application. Using this solution, many 
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settings files could be created, each capable of launching a 
different application. These settings files could then reside any- 
where in the file system, with a single program acting as the 
dispatcher of applications, according to the data contained in 
each separate launch settings file. Hence the name “dispatcher”. 


Remembering the Launch Parameters 

To launch a target application, and tie in an associated 
launch document, the dispatcher program stores two datarecords 
in each launch settings file. The two records are the same, each 
containing the name of the file, the directory ID of its parent 
folder,andthename ofthe volume containing thedirectory (if the 
file is at the volume root level, the directory number is 2 and the 
directory name is the same as the volume name). Some additional 
information is also stored with each of the two records to help 
with the launch. The filetype is remembered, and can be used 
when it’s necessary to ask the user to help find a file that has 
changed location. Also as part of the data, a flag is stored that 
determines whether or not the target application will be told to 
open the document after it is launched. 

Given that multiple dispatcher settings files can be present, 
it has to be easy to initialize and update the data in each one. To 
permit this, the dispatcher program tests the command key before 
launching the target application. If the key is down, a dialog 
window is presented that allows the user to alter the previous 
settings directly, or to change the settings by searching for the 
application and its associated document using the standard file 
dialog. It is also possible to set or unset the flag that determines 
whether the application should be instructed to open the associ- 
ated document. 


About Launching 

Apple Technical Support has provided detailed code ex- 
amples illustrating how to launch one program from another (in 
tech notes 52 & 126). I’ve based my code on these notes, 
including the recommendation not to use sublaunches. Avoiding 
sublaunches was not a significant limitation in my particular 
application, since there was no need to regain control after the 
launched application finished. In the event that you do use the 
sublaunch feature, its interesting to note that the Launch routine 
is now a function that returns a result when run under Multifinder. 
Youcan test the result of the launch and inform the user of errors. 
However, it turns out that a sublaunch, rather than a launch, must 
be performed in order to have Multifinder return a result code that 
can be processed by the sublaunching program. 

The overall process of launching an application with the 
dispatcher requires a number of steps (Figure 1). The process 
begins with the user opening (by double-click or menu) the 
dispatcher settings file. This causes the Finder to load the data 
document's working directory reference number (as well as other 
information) into the Finder information record referenced by the 
AppParmHandle global, and then launch the dispatcher. When 
the dispatcher gets control, it uses GetAppFiles to obtain the 
reference number of the settings file. This number is then used to 
locate and open the file forreading/writing. The two data records, 
one for the target application and one for the associated docu- 
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Facial Pain Record 4th Dimension® 


Launch Sequence 


1) User double clicks on settings file 
2) Finder launches Dispatcher 


3) Dispatcher launches target application 
4) Application opens associated document 


Figure 1 


ment, are read in. If the dispatcher can open the file, but can't read 
any records, it assumes the data has not been initialized, and sets 
up some initial dummy data. Normally this is not necessary, since 
new data documents can be created by duplicating existing 
documents and then editing the existing settings. However, when 
setting up the dispatcher for the first time, a file utility needs to 
be used to create the first data document. Remember to set the 
filetype to 'LCHD', the dispatcher’s settings file filetype (the 
dispatcher’s filetype is LCHA). 

Having read in the necessary launch parameters, the dis- 
patcher must now take care of some housekeeping related to the 
Finder information that will be passed on to the target applica- 
tion. First the AppParmHandle is obtained from the system 
global variable at memory location $AEC. The current heap zone 
is set to the system heap, and the existing handle is disposed. A 
new handle is allocated in the system heap allowing sufficient 
space for the information related to a single target application 
document. Then the current heap pointer is set back to the 
application's heap. I can recall the admonition in one of Apple's 
early Macintosh training courses to avoid allocating anything in 
the cramped system heap of the 128K and 512K Mac’s. Fortu- 
nately, Apple now provides a larger, variable size system heap 
and looks more favorably (I think) on developers allocating 
structures there. 

With a new Finder information record allocated, the launch 
data is loaded into records corresponding byte-for-byte to the 
Finder information records, and the records are copied to the 
system heap at the location referenced by the newly allocated 
handle. This handle is then loaded into the system global at 
location $AEC. Be sure to note that if the target application is to 
be launched without an associated document, then the Finder 
information must be zeroed out correctly, since the Finder will 
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not be intervening to perform its usual housekeeping. With the 
application parameters correctly loaded, all that is left to do is to 
set the default working directory to the target application’s 
directory and call the launch routine. 


Navigating the HFS 

Something should be said about the way the dispatcher 
navigates the hierarchical file system. Afterthe targetapplication 
and document are initially located, the dispatcher must assure 
that enough information is saved to permit them to be located on 
. Subsequent invocations. 

To adequately specify a file to the file system, a number of 
options are available. A full pathname from the root volume is 
one possibility. However, tech note #238 discourages this, since 
the file’s directory may be moved, making the pathname invalid 
(also note that system 7.0 will provide unique 32 bit file ID 
numbers). For current system versions, the dispatcher remem- 
bers the filename, directory ID number, and the volume name, 
and uses them together to locate the target file. Since multiple 
volumes may be mounted, the program checks the stored volume 
name against each mounted volume for a match. It is possible that 
two volumes might have the same name and confuse the dis- 
patcher, but this is uncommon and left as an enhancement to the 
program. Having located the volume, the program tests for the 
presence of the target file by using the filename and directory ID 
number. This process is carried out for both target files (applica- 
tion and associated document) and, if successful, is followed by 
the opening of working directories for both files. 

A number of errorscan occur while trying to locate the target 
files. Most commonly, one or both of the files might have been 
moved to another directory and/or volume. If this occurs, the 
program responds by asking the user to find the missing files, 
using the standard file dialog. As each file is found, the volume 
name, directory ID, and filename are saved so as to be available 
during the next use of the dispatcher. After the correct location 
information is obtained, it is written back to the settings file prior 
to launching the target application. If any unrecoverable errors 
occur, or the users cancels any of the dialogs, the dispatcher 
terminates without carrying out the launch. 

One other point that should be made comes from personal 
experience with the dangers of using PBHSetVol. Anyone con- 
sidering using the low level file manager calls should make sure 
they read tech note #140. Normally, most file manager calls will 
accepta working directory reference number in place of a volume 
reference number. This maintains compatibility between the flat 
and hierarchical file systems. Unlike other calls though, 
PBHSetVol has the habit of taking a working directory reference 
number in ioVRefNum and then setting the default directory 
back to the root. This can cause more than a few minutes of 
confusion trying to find out why files suddenly can't be found. 


Using and Extending the Dispatcher 
The dispatcher program has been written to require minimal 
user intervention. Ideally, a typical user should not even know 
that an intermediate program has been part of the launch of the 
target application. However, when initializing the file location 
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data, or accommodating the movement of a file to a new location, 
the dispatcher's settings dialog must be used (Figure 2). Its 
occasionally useful to view the dialog just to confirm what the 
settings are, especially if the settings haven't been used in a 
while. The information presented in the dialog is very simple. 
Twoedittext items are present to allow the user to enter the name 
of the target application and associated document. A check box 
item is also present that lets the user specify whether the applica- 
tion should be launched with or without the associated document. 


” А ч 


= 
e Dispatcher e > 


Current Settings Direct Drive 20 


Application Name: 


4th Dimension® v1.0.6 


Document Neme: 


ШІПЕСІГІ Бала Қ 


64 Open App Document 


Ө Verity Software Systems 1989 
by Roger Horton ЯН Rights Reserved 


Figure 2 


A second method to specify the target file data is also 
provided. A “Search” button is present that, when pressed, sets 
the filenames to “ХХХХХХХХ” and goes directly to the stan- 
dard file dialogs to locate the files. This method completely clears 
the previous filenames, and normally is used when new settings 
are being created. 

As mentioned above, the dispatcher program and data docu- 
ments can be located anywhere in the file system. This has been 
especially handy for me when using Multifinder. I’m sure that 
any Multifinder user is familiar with the desktop clutter that 
occurs when more than one application is open. Having a lot of 
Finder folders open on the desktop only adds to this clutter. My 
solution is to keep a set of dispatcher settings files directly on the 
desktop corresponding to the projects on which I’m currently 
working (Figure 3). All other folders are kept closed. This makes 
for much less clutter, and saves me the trouble of opening and 
Closing folders as I launch each application. 

In my case, the original purpose of the dispatcher was to 
make installation and launching easier for users of 4th Dimen- 
sion custom applications. My database application is supplied 
with the dispatcher located in a folder amongst the other 4D files. 
The settings file is located outside this folder. Installation simply 
involves copying the settings file and database folder onto the 
user's hard disk. The user never has to look inside the database 
folder, except from the standard file dialog when first installing 
the program. If the volume on which the application is to be 
installed happens to be known ahead of time, then its possible to 
completely preconfigure the settings file. 

Its easy to conceive of some enhancements to the dispatcher 
that would make it more useful. Options could easily be added to 
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Figure 3 


allow more than one data document to be associated with the 
target application. In this way, an application could be opened 
with a number of associated documents, similar (although much 
more limited) to a user startup script in the MPW environment. 
Provision could also be made for retention of the location of the 
dispatcher program in the data documents. This would make it 
possible to use the dispatcher with Finder substitutes. The dis- 
patcher could also be made tocreate its own settings files, making 
initial use of the program simpler. Its very likely that future 
developments in the Mac operating systems (real file aliasing, 
etc.) will help provide for some of the features of the dispatcher 
program. But for the time being, it provides users with an 
intuitive method of launching custom database applications. 
Beyond that, it can help to reduce desktop clutter while providing 
a general method for launching any application with an associ- 
ated document. 


NENNEN Mi — — ——-F.? 


Listing: dispatcher .aake 


dispatcher ff dispatcher .r 
Rez dispatcher.r -o dispatcher -append 
SetFile -a B dispatcher -c LCHA -t APPL 
dispatcher ff dispatcher .p.o 
Link dispatcher .p.o à 
“(Libraries)’Interface.o д 
“(Libraries)*Runtime.o д 
“(PLibraries}*Paslib.o 9 
-o dispatcher 


dispatcher .p.o f dispatcher .p 

Pascal dispatcher .p 
Listing: Dispatcher .p 

File: dispatcher .p 

Program: dispatcher 

Author : Roger A. Horton 

Verity Software Systems 
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Copyright 1989, All Rights Reserved 


Creation: 6/4/89 
Purpose: Create a small utility program to launch applica- 
tions 


from the Finder with associated launch documents. This 

is especially useful for custom applications that require 
a number of files, and that may cause a user confusion in 
installing and launching the application. 

Technique: This program performs a launch (not a sub launch ) 
using the code of Mac Tech Note #126 as a model. The utility 
does not directly initiate the launch, but relies on associ- 
ated 
data documents to initiate the process, and to determine 
which application and documents are to be launched. The 
launch utility and document(s) cen be located anywhere in 
the file system. By double clicking on a launch document, 
the user causes the Finder to locate and launch the launch 
utility program. The utility then reads the launch data 
document to obtain the name and location of the application 
and its associated document. The Finder application parameters 
are then set up, and the application is launched. If the 
location of the application or its associated documents has 
changed since the last launch, the user is prompted to find 
their new location. In essence, the launch utility documents 
act as aliases for target applications, and add additional 
usefulness by providing for automatic control of associated 
application documents. 

Program History: 


program scan; 
($0* ( Macsbug/TMON symbols ) 
($R-} ( Turn off range checking } 
uses 
( Macintosh toolbox units } 
PasLibIntf ,Memtypes, QuickDraw, OSIntf , ToolIntf ,PackIntf, 
SANE, PrintTraps, ROMDefs 
( Custom units } 


const 
active = 0; ( for use in controls and menus } 
inactive = 255; 
Df1tDlogID = 200; ( resource ID for config dialog ) 


D= 
StopDlogID = 201; ( resource ID for stop alert dialog ) 


AppParmGVarz $AEC; ( AppParmHandle sys global variable ) 


ype 
( general types ) 
pLaunchStruct = ^LeunchStruct; ( Launch record ) 
LaunchStruct = record 
pfName: ^Str255; ( pointer to application name ) 
param: integer; ( alternate video,eudio buffers ) 
LC: packed array[@..1] of char; ( extended parameters ) 
extBlockLen: longint; ( extra block length ) 
fFlags: integer; ( finder file info flags ) 
launchFlags: longint; ( bits 30,31 = 1 for sublaunch ) 


end; 

FileLInfo = record ( Finder files ) 
vRefNum: integer; ( 2 bytes ) 
fType: OSType; ( file type - 4 bytes ) 
version: boolean; ( 1 byte ) 


unused: boolean; ( 1 byte ) 
fName: Str255; ( 1 length byte, variable length string ) 


end; 
APHd! = ^APPtr; (Finder info ) 
APPtr = ^APRec, 
APRec = record 


message: integer; ( 2 bytes ) 
count: integer; ( 2 bytes ) 
files: аггау[1..1) of FileLInfo; 
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end; 
LaunchData = record (application & document data settings) 
vName: Str255; ( volume name ) 
vRefNum: integer; ( working directory reference 8 ) 
dirID: longint; (directory ID # } 
fName: Str255; ( file name ) 
fTupe: OSTupe; ( file tupe ) 
uselt: integer; ( whether to open associated document ) 
end; 
var 
( file system parameter blocks } 
myPB: ParamBlockRec; 
myHPB: HParamBlockRec; 
myInfoPB: CInfoPBRec; 
myWDPB: WDPBRec; 
( launch data records } 
appLData: LaunchData; 
docLData: LaunchData; 
( niscellaneous ) 
done: integer; 
lent: integer; 


( application ) 
( document ) 


( done flag ) 
( loop counter ) 


( ****** Utility functions and procedures ***xxx ) 
procedure AlertMsg(msgStr1, msgStr2:Str255); 
( Procedure to print alert message. 
To print numerics, use something like this: 
testStr1, testStr2: Str255; 
NumToString(reqOnt, testStr 1); 
NumToStringCreqCnt, testStr2); 
AlertMsgCtestStr1, testStr2); ) 
var 
theRect :rect; 
ignore: integer; 
begin 
PeremText(msgStri, msgStr2, ”, ©); 
ignore := StopAlert(StopDlogID,NIL); 
end; (procedure AlertMsg ) 


( жжжжжжжжк Error Handling ххххххжжжж ) 


function GetErrorMsg(result:0SErr):string; 
begin 
result := abs(result); 
case result of 
18: GetErrorMsg 
19: GetErrorMsg 
20: GetErrorMsg 
27: GetErrorMsg 
Operation’; 
28: GetErrorMsg 
33: GetErrorMsg 
34: GetErrorMsg 
are full’; 
35: GetErrorMsg 
36: GetErrorMsg 
37: GetErrorMsg 
39: GetErrorMsg 
40: GetErrorMsg 
of file’; 
42: GetErrorMsg 
43: GetErrorMsg 
44: GetErrorMsg 
setting’; 
45: GetErrorMsg 
46: GetErrorMsg 


‘driver error during status operation’; 
‘driver error during read operation’; 
‘driver error during write operation’; 
‘driver I/0 error caused abort of 


‘driver not open’; 
‘the file directory is full’; 
‘all allocation blocks on the volume 


‘the specified volume is not mounted’; 
‘there was an unspecified I/0 error’; 
‘the file or volume name is bad’; 
‘logical EOF reached unexpectedly’ ; 
‘attempt made to position before start 


‘too many files аге open’; 
‘the file could not be found’; 
‘the volume is locked by hardware 


‘the file is locked’; 
‘the volume is locked by a software 


47: GetErrorMsg 
48: GetErrorMsg 
49: GetErrorMsg 


‘the file is already in use’; 
‘a file with specified name exists’; 
‘the file is already open for read/ 


90: GetErrorMsg 
volume’ ; 

51: GetErrorMsg 

52: GetErrorMsg 


‘no volume specified and no default 


‘a non-existent path was specified’; 
‘the was an error finding current 
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position in file’; 

53: GetErrorMsg 

54: GetErrorMsg 
writing’; 

55: GetErrorMsg := ‘attempt to mount an already mounted 
volume’; 

56: GetErrorMsg := ‘the specified drive number is not 
mounted’; 

57: GetErrorMsg := “the volume lacks a Macintosh format 
directory’; 

98: GetErrorMsg 
error’; 

59: GetErrorMsg := ‘there was a problem during renaming’; 

60: GetErrorMsg := ‘the master directory block is bad’; 

61: GetErrorMsg ‘read/write permission does not allow 
writing’; 

108: GetErrorMsg := ‘there is insufficient application 
memory’; 

109: GetErrorMsg := ‘a nil master pointer has been 
encountered’; 

111: GetErrorMsg 

112: GetErrorMsg 

117: GetErrorMsg 

120: GetErrorMsg 

121: GetErrorMsg 
open’; 

122: GetErrorMsg := ‘a folder cannot be placed in its own 
subfolder’; 

123: GetErrorMsg := ‘attempt HFS operations on non-HFS 
volume’ ; 

127: GetErrorMsg := ‘there was an internal file system 
error’; 

e : GetErrorMsg := ‘printing aborted at user request’ ; 

eng; 
end; ( function GetErrorMsg ) 


‘the specified volume is not on-line’; 
‘attempt to open a locked file for 


‘there was an external file system 


‘attempt to operate on a free block’; 
‘attempt to purge a locked block’; 
‘the block is locked’; 

‘the directory could not be found’; 
‘too many working directories are 


procedure [0Check(result:0SErr); 
var 
ignore: integer; 
errorString:Str255; 
begin 
f result © NoErr then 
begin 
NumToStringCresult, errorString); 
ParamText( ‘Macintosh OS Error 8:”, errorString, ‘Macin- 
tosh 0S Error Desc:’, GetErrorMsg(result)); 
ignore := StopAlert(StopDlogID,NIL); 
end 
end; (procedure IOCheck ) 


procedure LaunchFailed(errNo:0SErr); 

var 
ignore: integer; 
errorString:Str255; 

begin 
NumToStr ingCerrNo, errorStr ing); 
PeramTextC'Launch Error #:“ errorString, ^, 2); 
ignore := StopAlert(StopDlogID,NIL); 

end;  ( procedure LaunchFailed ) 


procedure NotFoundMsg(str 1,str2:Str255); 
var 

ignore: integer; 
begin 

ParamText( ‘Please help locate’, str1, str2, ‘using the 
following dialog... 7’); 

ignore := StopAlert(StopDlogID, NIL); 
end;  ( procedure LaunchFailed ) 
( XXXx* xx xxx Conf iguration routines XXXXXXXKXXXKXXK ) 
function ReadDefaultData: integer; 
( Open the launch data file and read the data necessaru for 
ш. launch application and associated document Cif anu). 
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var 
theErr: OSErr; 
myAppFile: AppFile; 
myRefNum: integer; 
theResult: integer; 
appMsg: integer; 
appCount: integer; 
begin 
theResult := Ø; (бе optimistic ) 
CountAppF i lesCappMsg, appCount); 
if appCount < 1 then 
begin 
theResult := 1; 
AlertMsg( ‘Dispatcher must be launched’, "from a data 
document’); 
( could create a new data document file instead ) 
end 
else 
begin 
GetAppFiles(1, myAppFile); 
( open the file for reading ) 
muPB.ioCompletion := nil; 
myPB.ioNamePtr := @myAppFile.fName; 
nyPB . ioVRef Num myAppF ile.vRefNum; 
myPB.ioPermssn := fsRdWrPerm; ( read/write permission ) 
myPB.ioMisc := nil; ( use volume buffer ) 
theErr := PBOpen(@myPB, false); 
if theErr © noErr then 


begin 
IOCheckCtheErr?; 
theResult := 1; 
end 
else 
begin 


muRefNum := myPB.ioRefNum; 

( read the application launch data ) 
myPB.ioCompletion := nil; 

myPB.ioRefNum := myRefNum; 

myPB.ioBuffer := @appLData; 

myPB.ioReqCount := sizeof (LaunchData), 
myPB.ioPosMode := fsAtMark; 

myPB.ioPosOffset := 0; 

theErr:= PBRead(@muPB, false); 

if ((theErr © noErr) or (myPB.ioActCount < 1)) 


then 
begin 
appLData.vName := ‘Uninitialized’; 
appLData.dirID := 0; 
appLData.fName := ‘Uninitialized’; 
appLData.fType := ‘APPL’; 
applData.useIt := 1; ( not used } 
end; 
( read the document launch data } 
myPB.ioCompletion := nil; 
myPB.ioRefNum := myRefNum; 
myPB.ioBuffer := @docLData; 
myPB.ioReqCount := sizeofCLaunchData); 
myPB.ioPosMode := fsAtMark; 
myPB.ioPosOffset := 0; 
theErr := PBRead(@myPB, false); 
if (CtheErr © noErr) or CmyPB.ioActCount < 1)) 
then 
begin 
docLData.vName := ‘Uninitialized’; 
docLData.dirID := 0; 
docLData.fName := ‘Uninitialized’; 
docLData.fType := ‘TEXT’; 
docLData.useIt := 1; 
end; 
( close the data file ) 
myPB.ioCompletion := nil; 
myPB.ioRefNum := myRefNum; 
theErr:-» PBCloseC@myPB, false); 
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end; ( if data file opened OK ) 
end; (if app files count is > 0) 
ReadDefaultData := theResult; 
end;  ( procedure ReadDefaultData ) 


function WriteDefaultData: integer; 
( Open the launch data file and write the data necessary for 
locating launch application and associated document Cif any). 
This should take place any time the data is changed. } 
var 
theErr: OSErr; 
myAppFile: AppFile; 
myRefNum: integer; 
theResult: integer; 
begin 
theResult := 0; (бе optimistic ) 
GetAppFilesC1, myAppFile); 
( open the file for reading/writing } 
myPB.ioCompletion := nil; 
myPB.ioNamePtr := @myAppFile.fName; 
myPB.ioVRefNum := myAppFile.vRefNum; 
myPB.ioPermssn := fsRdWrPerm; ( read/write permission ) 
myPB.ioMisc := nil; ( use volume buffer } 
theErr := PBOpen(@myPB, false); 
if theErr © noErr then 


begin 
IOCheckCtheErr?; 
theResult := 1; 
end 
else 
begin 


myRefNum := myPB.ioRefNum; 

( write the application launch data ) 
myPB.ioCompletion := nil; 

nyPB.ioRefNum := myRefNum; 

myPB.ioBuffer := @appLData; 

myPB.ioReqCount := sizeof (LaunchData); 
myPB.ioPosMode := fsAtMark; 

myPB.ioPosOffset := 0; 

theErr:= PBWriteC@myPB, false); 

if (CtheErr € noErr) or (myPB.ioActCount < 1)) then 


begin 
IOCheckCtheErr); 
theResult := 1; 
end 
else 
begin 


write the document launch data } 
myPB.ioCompletion := nil; 
myPB.ioRefNum := myRefNum; 
myPB.ioBuffer := @docLData; 
myPB.ioReqCount := sizeof (LaunchData); 
myPB.ioPosMode :- fsAtMark; 
myPB.ioPosOffset := Ø; 
theErr := PBWriteC@myPB, false); 
if (CtheErr © noErr) or CmyPB.ioActCount < 1)) 
then 
begin 
10Check( theErr 2; 
theResult := 1; 
end; ( if bad document write ) 
end; ( if application write OK ) 
( close the data file ) 
myPB.ioCompletion := nil; 
nyPB. ioRefNum := myRefNum; 
theErr:- PBCloseC@myPB, false); 
end; ( if data file opened OK ) 
WriteDefaultData := theResult; 
end;  ( procedure WriteDefaultData ) 


functionFindApplFile: integer; 

( Given the info in the data document, try to find the 
target 
application” working directory reference number. If it can't 
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be found, then prompt the user to find it. ) 


var 


theErr: OSErr; 
theResult: integer; 
reply: SFReply; 
topLeft: Point; 
fileFilter: SFTypeList; 
appdone, appfound: integer; 
theName: Str255; 
theIndex: integer; 
theRefNum: integer; 
begin 
theResult := 0; (be optimistic ) 
( see if the volume is mounted ) 
theIndex := 1; 
appdone := 0; appfound := Ø; theName:= ““; 
repeat 
myHPB. ioVolIndex := theIndex; 
myHPB. ioCompletion := NIL; 
mygHPB.ioNamePtr := @theName; 
theErr := PBHGetVInfoC@myHPB, false); 
if theErr © noErr then 
appdone := 1;  ( no more volumes to check ) 
1? theName = appLData.vName then 
begin 
appfound := 1; appdone := 1; 
theRefNum := myHPB.ioVRefNum; 
end; 
thelndex := thelndex + 1; 
until appdone » 0; 


1f appfound = 0 then 
theResult := 1 
else 
begin 
see if file can be found } 
myHPB. ioCompletion := NIL; 
туНРВ. ioNamePtr := @appLData.fName; 
myHPB.ioVRefNum := theRefNum; ( from call above ) 
myHPB.ioFDirIndex := 0; ( use file name, not index ) 


myHPB.ioDirID := appLData.dirID; ( use stored Dir ID ) 


theErr := PBHGetF InfoC@myHPB, false); 
1f CtheErr © noErr) then 
begin 
T0Check(theErr); } 
theResult := 1; 
end 
else 
begin 
get the current application WD Ref Num } 
myWDPB. ioCompletion := nil; 
myWDPB.ioNamePtr := nil; ( directory name ) 
myWDPB.ioVRefNum := theRefNum; 
myWDPB.ioWDProcID := longintC'ERIK ^); 
myWDPB.ioWDDirID := appLData.dirID; 
theErr := PBOpenWDC8myWDPB, false); 
appLData.vRefNum := myWDPB.ioVRefNum; 
IO0CheckCtheErr?); 
end; (getting the current WD Ref Num ) 
end;  ( if volume was found OK ) 


( if application couldn't be found using default informa- 
tion, make the user find it manually. ) 
if theResult © Ø then 
begin 
NotFoundMsg('the program file: ',appLData.fName); 
topLeft.h := 80; topLeft.v := 70; 
fileFilter(0] := appLData.f Type; 
SFGetF ileCtopLeft, ^^, NIL, 1,fileFilter,NIL,reply); 
if reply.Good then 
begin 
theResult := 0; (reset the error flag ) 
appLData.vRefNum := reply.vRefNum; ( WD RefNum ) 
appLData.fName := reply.fName; 
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appLData.f Type :- replu.fTupe; 
( look up new volume name } 
myHPB.ioCompletion := NIL; 
myHPB.ioNamePtr :- @appLData.vName; 
nyHPB. ioVRefNum := appLData.vRef Nun; 
myHPB.ioVollndex := 0; ( use vRefNum, not name ) 
theErr :- PBHGetVInfoC@myHPB, false); 
I0CheckCtheErr); 
( look up new application directory ID ) 
myInfoPB.ioCompletion := nil; 
myInfoPB.ioNamePtr:= éappLData.fName; 
myInfoPB.ioVRefNum := appLData.vRefNum; 
myInfoPB.ioFDirIndex := 0; 
myInfoPB.ioDirID := 8; 
theErr := PBGetCatInfoC@myInfoPB, false); 
I0CheckCtheErr?; 
appLData.dirID := myInfoPB.ioFLParID; 
( update the default data ) 
if WriteDefaultData © 0 then 
theResult := 1; 
end ( if replu is good ) 
else 
begin 
theResult := 1; 
end; ( user cancelled application lookup } 
end; ( if default application location not valid ) 
FindApplFile := theResult; 
end;  ( procedure FindApplFile ) 


function FindDocFile: integer; 
( Given the info in the data document, try to find launch 
document’s working directory reference number. If it can't 
be found, then prompt the user to find it. ) 
var 
theErr: OSErr; 
theResult: integer; 
reply: SFReply; 
topLeft: Point; 
fileFilter: SFTypeL ist; 
docdone, docfound: integer; 
theName: Str255; 
theIndex: integer; 
theRefNum: integer; 
begin 
theResult := 0; (be optimistic ) 


( see if there is an associated document with application ) 
if (docLDeta.useIt = 1) then ( launch with associated 
document ) 
begin 
see if the volume is mounted ) 
theIndex := 1; 
docdone := Ø; docfound := 0; theName:= ‘’; 
repeat 
myHPB. ioVolIndex := theIndex; 
myHPB.ioCompletion := NIL; 
myHPB. ioNamePtr :- @theName; 
theErr := PBHGetVInfoC@myHPB, false); 
if theErr <> noErr then 
docdone 1; (по more volumes to check ) 
1f theName = docLData.vName then 
begin 
docfound := 1; docdone := 1; 
theRefNum := myHPB.ioVRefNum; 
end; 
theIndex := theIndex + 1; 
until docdone > 0; 


1f docfound = 0 then 
theResult := 1 
else 
begin 
See if the file can be found in its directory } 
myHPB. ioCompletion := NIL; 
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muHPB.ioNamePtr := edocLData.fName; itemRect: Rect; 
myHPB.ioVRefNum := theRefNum; ( from call above ) df 1tDlg: DialogPtr; 
myHPB. ioFDirIndex := Ø; (use file name, not index) itemHdl1, itemHd12: Handle; ( edittext handles ) 
muHPB.ioDirID := docLData.dirID; (use stored Dir ID) itemHd13: Handle; ( check box dialog handle } 
theErr := PBHGetF InfoC@myHPB, false); сВохНа11: ControlHandle; ( check box control handle ) 
if (theErr <> noErr) then theResult: integer; 
begin begin 
10Check(theErr); } theResult := 0; 
theResult := 1; ( get dialog & edittext handles } 
end dfltDlg := GetNewDialogCDfltDlogID, nil, Pointer(-1)); 
else GetDItem(dfltD1g, 4, itemType, itemHdl1, itemRect); 
begin GetDItemCdfltDlg, 5, itemType, itemHd12, itemRect); 
get the current document WD Ref Num ) GetDItemCdfltDlg, 6, itemType, itemHdl3, itemRect); 
myWDPB.ioCompletion := nil; cBoxHd11 := ControlHandleCitemHd13); 
myWDPB.ioNemePtr := nil; ( directory name ) SetITextCitemHdl1, appLData.fName); ( app filename ) 
myWDPB.ioVRefNum := theRefNum; SetITextCitemHd12, docLData.fName); ( doc filename ) 
myWDPB.ioWDProcID := longintC'ERIK ^2; SetCtlValueCcBoxHdli1, docLData.uselt?); ( use/don't use 
myWDPB.ioWDDirID := docLData.dirID; document ) 
theErr := PBOpenWDCemyWDPB, false); 
docLData.vRefNum := myWDPB.ioVRefNum; ( put up dialog ) 
10Check( theErr); itemHit := 0; 
end; (getting the current WD Ref Num ) while CCitemHit > 3) or CitemHit < 1)) do 
end; ( if volume was found OK ) begin 
ModalDialog(nil, itemHit); 
( if document couldn't be found using default information, if itemHit = 6 then ( toggle the check box ) 
make the user find it manually. ) begin 
if theResult «> 0 then if (GetCtlValue(cBoxHd11) = 0) then 
begin SetCt]Value(cBoxHdl1, 1) 
NotFoundMsg( ‘the associated document: else 
‘ docLData.fName); SetCtlValueCcBoxHdl1, 0); 
topLeft.h := 80; topLeft.v := 70; end; 
fileFilter(@] := doclData.f Type; end; (while } 
SFGetF ileCtopLef t, ^^, NIL,-1,fileFilter,NIL,reply2; ( get dialog results ) 
16 reply.Good then case itemHit of 
begin 1: begin ( use names entered in dialog ) 
theResult := 0; ( reset the error flag ) ( application name ) 
docLData.vRefNum := reply.vRefNum; GetITextCitemHdl1, appLData.fName); 
docLData.fName := reply.fName; ( document name ) 
docLData.fType := reply.fType; GetITextCitemHd12, docLData.fName); 
( look up new volume name y end; 
myHPB. ioCompletion := nil; 2: begin ( cause a search for new files ) 
docLData.vName := “°; appLData.fName := "ХХХХХХХХ”; 
myHPB.ioNamePtr := @docLData.vName ; docLData.fName := ‘XXXXXXXX?; 
myHPB. ioVRefNum := docLData.vRefNum; end; 
myHPB.ioVolIndex := Ø; ( use vRefNum, not name } 3: theResult := 1; ( cancel the launch ) 
theErr := PBHGetVInfoC@myHPB, false); end; 
( look up new document parent directory ID } if (theResult = 0) then 
nyInfoPB.ioCompletion := nil; begin 
myInfoPB.ioNamePtr := @docLData. fName; docLData.useIt := GetCtlValueCcBoxHd1 1); 
nyInfoPB.ioVRefNum := docLData.vRefNum; theResult := WriteDefaultData; ( update the defaults ) 
myInfoPB.ioFDirIndex := 0; end; 
myInfoPB.ioDirID := 0; DisposDialog(dfltD1g); 
theErr := PBGetCatInfoC@myInfoPB, false); EditDefaults := theResult; 
IOCheck(theErr); end; ( EditDefaults ) 
docLData.dirID := myInfoPB.ioFLPerID; 
( parent directory ID } function TestCommandKey: integer; 
( if command is held down while starting, the user will 
( update the default data } be allowed to edit the default settings. The file data 
if WriteDefaultData € 0 then has already been read at this point. If the user cancels, 
theResult := 1; the data defaults are not changed. } 
end (if reply is good } var 
else theResult: integer ; 
begin eventReady: boolean; 
theResult := 1; myEvent: EventRecord; 
end; (user cancelled document lookup ) begin 
end; ( if default document location not valid ) theResult := 0; 
end; ( if associated document exists ) eventReadu := GetNextEventCeveryEvent, myEvent); 
FindDocFile := theResult; 1f (BAND(myEvent.modifiers,cmdkey) > 0) then 
end; ( procedure FindDocFile } theResult := EditDefaults; 
TestCommandKey := theResult; 
function EditDefaults: integer; end;  ( TestCommandKey } 
var 
itemHit: integer; ( x*xxxxxxX | Transfer and launch routines ****xeeExEX ) 


itemType: integer; 
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function ResetF inderInfo: integer; 

( This is an example of how the finder parms could be changed 
without allocating a new structure in the system heap. 
However, the changes could not exceed the size of the existing 

heap object. This routine is not used. ) 
var 
fInfoHdl: Handle; 
hSize: integer; 
appParmRec: APRec; 
theResult: integer; 
begin 
theResult := 0; ( Ье optimistic ) 
( get AppPermHandle, lock it, and copy parms record ) 
fInfoHdl := HandleCAppParmGVar ); 
fInfoHdl := HendleCfInfoHdl^); 
HLock(f Inf oHd1); 
hSize := GetHandleSizeCfInfoHd]); 
BlockMoveCPointer(CfInfoHdl^), Pointer(@appParmRec), hSize); 
1f CappParmRec.count > 0) then 
begin 
if ClengthCappParmRec.f iles( 11.f Name) >= 
lengthCdocLData.fName)) then 
begin 
now change the launch parameters ) 
appPaermRec.files[1].fName := docLData.fName; 
appParmRec.files(1].fType := docLData.f Type; 
eppParmRec.files[1].vRefNum := docLData.vRefNum; 
BlockMove(Pointer(@appParmRec), Pointer(f InfoHd1^), hSize); 
end 


( my Finder info } 


end 
else 
begin 
AlertMsgC'Unable to reset’, ‘launch file parameters’): 
theResult := 1; 


end; 
HUnlockCf InfoHd1); 
ResetFinderInfo := theResult; 
end;  (ResetFinderInfo ) 


function ZeroF inderInfo: integer; 
( If no associated documents are needed, then the number of 
files in app parm handle block must be set to zero, and 
the file types set to zero so the Finder cen clean up when 
it gets control back. The number of files will always be 1 
when this routine is called. ) 
var 
f InfoHdl: Handle; 
hSize: integer; 
appParmRec: APRec; ( my Finder info ) 
theResult: integer; 
begin 
theResult:= 0; (ре optimistic ) 
( get handle, lock it, and copy parms record ) 
flnfoHd] := HandleCAppParmGVar ); 
fInfoHdl := Handle(fInfoHd1*); 
HLock(f InfoHd1); 
hSize := GetHandleSize(fInfoHd1); 
BlockMove(Pointer(f InfoHd1^), PointerC@appParmRec), hSize); 
if CappParmRec.count > 0) then 
begin 
now change the launch parameters ) 
appParmRec.count := 0; 
eppParmRec.files[1].fType := OSTgpeClongint(2)); 
( write it back out ) 
BlockMove(Pointer(@appParmRec), Pointer(fInfoHd1*), hSize); 
end; 
HUnlockCf InfoHd1); 
ZeroFinderInfo := theResult; 
end;  (ZeroFinderInfo ) 


( Finder info handle } 


function ReplaceFinderInfo: integer; 

( To prepare for the launch, the finder launch information 
must be reset to hold the name and type of the database 
Startup file. This routine disposes the old AppParmHandle heap 
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object and allocates a new one on the system heap. Returns @ 
if successful, 1 if an error occurred. j 
var 


fInfoHdl: Handle; 
sysZone: THz; 
appZone: THz; 
hSize: integer; 
appParmRec: APRec; 
theErr: OSErr; 
theResult: integer; 
saveAppParm: ^longint; ( pointer used to access АЕС ) 


( handle to Finder info ) 
( system heap zone pointer ) 
( application heap zone pointer ) 


( my Finder info ) 


begin 


theResult := Ø; (бе optimistic ) 

( get handle, lock it, and copy parms record ) 

fInfoHd] := HandleCappParmGVar ); 

fInfoHdl := Handle(fInfoHd1*); 

HLock(f InfoHd1); 

hSize := GetHandleSize(fInfoHd1); 

BlockMove(Pointer(f InfoHdl^2), Pointer(@appParmRec), hSize); 


( dispose the old handle in the system zone) 
HUnlock(f Inf oHd12; 

appZone := GetZone; 

sysZone := SystemZone; 

SetZone(sysZone); 

DisposHand1le(f InfoHd1); 


( allocate a new handle in the system zone ) 
hSize := 13 + length(docLData.fName); ( enough for one doc ) 
fInfoHd] := NewHandleChSize); 
theErr := MemError; 
SetZoneCappZone); 
1f theErr € noErr then 
begin 
IO0CheckCtheErr); 
theResult := 1; 
end 
else 
begin 
HLock(f Inf oHd1); 
( put the new handle back at $AEC ) 
saveAppParm := PointerCAppParmGVar ); 
saveAppParm^ :- longint(fInfoHd!); 


( now change the launch parameters ) 
appPermRec.message:- 0; ( open it ) 
appParmRec.count:= 1; ( number of documents } 
appPermRec.files{1].vRefNum := docLData.vRefNum; 
eppPermRec.files([1].fType := docLData.fType; 
appParmRec.files[1].version := false; 
appPermRec.files{1].unused := false; 
eppParmRec.files[1].fName := docLData.fName; 
BlockMove(Pointer(@appParmRec), Pointer(f InfoHd1^), 


hSize); 


HUnlockCf Inf oHd1); 
end; ( if sys heap handle allocated OK ) 
ReplaceFinderInfo := theResult; 


end;  (ReplaceFinderInfo ) 


function LaunchIt(pLnch: pLaunchStruct): OSErr; 
( from tech note #52 & 126 ) 


INLINE $205F, $A9F2, $3E80; 


procedure DoLaunch; 
( Launch the application, given the information in the 


launch data records for the application & document. ) 


var 


fileInfo: FInfo; 
ignore: integer; 
myLaunch: LaunchStruct; 
theErr: OSErr; 


begin 


set default working directory to application’s folder } 
myWDPB.ioCompletion := NIL; 
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myWOPB.ioNamePtr := NIL; All rights reserved. 


myWDPB.ioVRefNum := applData.vRefNum; Resource definitions for dispatcher application 
theErr := PBSetVolC@myWDPB, false); Rez format 
*/ 
( get finder flags for launch record) “Чілсімде “Types.r’ 
mulnfoPB.ioNamePtr:= @appLData.fName, resource ‘BNDL’ С 128) ( 
myInfoPB.ioVRefNum := appLData.vRefNum; 'LCHA', 
myInfoPB.ioFDirIndex := Ø; ( use name instead of index ) 0, 
myInfoPB.ioDirID := 0; ( /* array TypeArray: 2 elements */ 
theErr := PBGetCatInfoCémyInfoPB, false); /* (1) */ 
' [CN ^, 
( now launch the application ) ( /* array IDArray: 2 elements */ 
myLaunch .pfName := @appLData.fName; /* (i) */ 
myLaunch.param := 0; 0, 128, 
myLaunch.LC := ‘LC’; /* [2] */ 
muLaunch.extBlockLen := 6; 1, 129 
muLaunch.LaunchFlags:= $00000000; (%С0000000 for sublaunch) ), 
muLaunch.fFlags := myInfoPB.ioFlFndrInfo.fdFlags; ( from /* [2] */ 
GetCatInfo ) “БЕР”, 
( /* array IDArray: 2 elements */ 
theErr ‘= Launch] tC@myLaunch); /* (1) */ 
if theErr < 0 then 0, 130, 
LauncnFailed(theErr); /* [2] */ 
end;  ( procedure DoLaunch ) 1, 131 
function PrepareForLaunch: integer; ) 
( set up the AppParmsHandle data ) J; 
var resource ‘ICN#’ (128, “Dispatcher Application Icon”) { 
theResult: integer; ( /* array: 2 elements */ 
begin /* (1) */ 
theResult := 0; $"FFFF FFFE 8000 0003 8120 0003 8120 0003" 
if (doclData.useIt = 1) then ( application & document ) %”8220 0003 8440 0003 8880 07С3 8118 1823" 
theResult := ReplaceFinderInfo %”861С 2023 B80F FF23 8006 0023 8005 0043" 
else ( application onlu ) $?8004 8043 8004 4083 800С 2083 800C 0103" 
theResult := ZeroF inder Info; $8014 0203 8014 0603 8024 0А03 8024 1203" 
PrepareForLaunch := theResult; $^8020 7203 8021 0203 801E 1203 8000 1203" 
end;  ( function PrepareForLaunch ) $^"8000 1203 8000 1203 8000 3303 8000 2103" 
%”8000 2103 8000 2103 FFFF FFFF ТЕРЕ FFFF^, 
procedure Initialize; /* [2] */ 
( initialize managers & globals ) $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
begin $"FFFF FFFF ҒҒҒҒ FFFF FFFF FFFF FFFF FFFF” 
initialize the managers ) $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF” 
InitGraf(@thePort); $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF” 
InitFonts; $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
InitWindows; $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
InitMenus; $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
TEInit; $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF* 
InitDialogsCNIL); ) 
FlushEventsCeveryEvent,0); ); 
end; ( Initialize resource ‘ICN#’ (129, “Dispatcher Document Icon”) ( 
( /* array: 2 elements */ 
( main program ) /* (1) */ 
begin $"FFFF FFFE 8000 0003 8000 1Е03 8000 0183" 
Initialize; $^8000 1C43 8000 0243 83С0 0123 8430 18A3" 
lent := 1; done := 0; $^8408 38A3 84FF F@A3 8400 6003 8200 A203" 
while done = 0 do %%8201 2003 8102 2003 8104 3003 8080 3003" 
begin %”8040 2803 8060 2803 8050 2403 8048 2403" 
case Іспі of $^804Е 0403 804B 8403 8048 7803 8048 0003" 
1: done := ReadDefaultData; $^8048 0003 8048 0003 80СС 0003 8084 0003" 
2: done := TestCommandKeu; $?8084 0003 8084 0003 FFFF FFFF ТЕРЕ FFFF^, 
3: done := FindApplFile; /* [2) */ 
4: done := FindDocFile; $"FFFF FFFE FFFF FFFF FFFF FFFF FFFF FFFF” 
5: done := PrepareForLeunch; $"FFFF FFrF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
6: DoLaunch; ( returns only if sublaunched ) $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
end; $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
lent := lent + 1; $“FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
if Icnt > 6 then done := 1; $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
end; (while } $"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF" 
end. ( dispatcher ) $^FFFF FFFF FFFF FFFF FFFF FFFF TFFF FFFF^ 
Listing: dispatcher.r ); 
resource ‘FREF’ С 130) ( 
/*dispatcher .r ‘APPL’, 
Copyright Verity Software Systems 1989 0, 
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“Dispatcher Application” 


resource ‘FREF’ (131) ( 
‘LCHD’, 

l 

“Dispatcher Document” 


data ‘LCHA’ (Ø) ( 

%”4469 7370 6174 6368 6572 2041 7070 6С69" 
/* Dispatcher Application */ 

$6361 7469 6F6E 2020 2043 6F70 7972 6967" 
/* Copyright 1989 Verity Software Systems. */ 

%”6874 2031 3938 3920 5665 7269 7479 2053" 

$"6F66 7477 6172 6520 5379 7374 6560 732E” 

$"2052 6F67 6572 2041 2E20 486F 7274 6F6E” 
/* Roger A. Horton */ 

$"2020 2041 6C6C 2072 6967 6874 7320 5265" 
/* - All rights Reserved */ 

%”7365 7276 6564" 


); StaticText ( 
resource ‘DLOG’ (200, "Configuration Settings”) ( enabled, 
(38, 116, 312, 390), “@ Verity Software Systems 1080” 
81 tDBoxProc, } 
visible, /* [12] */ 
noGoAway, (239, 15, 256, 128), 
0х0, StaticText ( 
200, enabled, 


) “Configuration Settings” 
resource ‘DITL’ (200, “Configuration Settings”) ( 
( /* array DITLarray: 13 elements */ 
/* (1) */ 
(184, 24, 204, 84), 
Button ( 
enabled, 
“ОК” 


), 
/* [2] */ 
(184, 109, 204, 169), 
Button ( 
enabled, 
“Search” 


/* [3] */ 
(184, 192, 204, 252), 
Button ( 

enabled, 

“Cancel” 


/* [4] */ 
(74, 31, 92, 239), 
EditText ( 

enabled, 

"4th Dimensione v1.0.6" 


), 
/* [5] */ 
(128, 30, 146, 238), 
EditText ( 
enabled, 
“FPR? 


), 
/* (6) */ 
(151, 56, 171, 212), 
CheckBox ( 
enabled, 
“Open App Document” 


/* UT] */ 
(4, 81, 24, 182), 
StaticText ( 
enabled, 
"о Dispatcher 0” 


/* (8) */ 
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(25, 75, 45, 190), 
StaticText ( 
enabled, 
“Current Settings" 


/* [9] */ 
(51, 31, 70, 239), 
StaticText ( 
enabled, 
“Application Name: ” 


/* [10] */ 
(106, 32, 125, 239), 
StaticText ( 
enabled, 
“Document М№ате: * 


уж {111 жу 
(220, 30, 238, 249), 


“by Roger Hor ton” 


/* [13] */ 
(239, 132, 256, 263), 
StaticText ( 

enabled, 

“All Rights Reserved” 


) 
); 
resource ‘ALRT’ (201) ( 
(80, 100, 210, 400), 
201, 
( /* erray: 4 elements */ 
/* (1) */ 
OK, visible, soundi, 
/* [2] */ 
OK, visible, soundl, 
/* [3] */ 
OK, visible, sound, 
/* [4] */ 
OK, visible, sound! 
); 
resource ‘DITL’ (201) ( 


( /* array DITLarray: 2 elements */ 


/* [1) */ 
(100, 125, 120, 175), 
Button ( 

enabled, 

“ОК ^ 


), 
/* [2] */ 
(10, 70, 90, 290), 
StaticText ( 
disabled, 
““@ \n*1 \n*2 An 3/ 


) 


resource ‘SIZE’ (-1) ( 
dontSaveScreen, 
ignoreSuspendResumeEvents, 
dontDoOwnAct ivate, 
128000, 
128000 


4 
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Pascal Procedures 
AACK gives AppleTalk Shell 


[Ajay Nath has two B.A.s, one in Chemistry and one in 
Mathematics. He is currently a second year medical student and 
is using Macs to develop Color Vision tests.] 


AACK OR ATApp? 

Example AppleTalk programs have appeared before in 
MacTutor but none recently except in one of the HyperCard 
columns. The introduction of MultiFinder,a new interface to the 
AppleTalk routines and new features added to AppleTalk itself, 
have changed the way applications should use AppleTalk. In this 
article I present a program called AACK, the “AppleTalk Appli- 
cation Construction Kit’, which was written in LightSpeed 
Pascal 2.0, which demonstrates how to use the new AppleTalk 
interface and how to use the background features of MultiFinder. 
The resources of the program were created by ResEdit and stored 
in a file called “aack.rsrc”, a rez description of the resources is 
found in the file “resources.r”. The code of the program is in 4 
files/units as follows: 


aack. т 


yu Runtime 110 
Interface lib 
ABPackage 116 
nAppleT alk.lib 
AppleT alk.p 
globals.p 
lowlevelatprocs.p 


globals.p global declarations 
lowlevelATprocs.p low level procs 

hooks.p code specific to the application 
main.p generic application code 


The code is designed to be easily modifiable. By simply 
changing code in the file hooks.p the nature of the applications 
produced can be changed. For example, in the file main.p, the 
code that handles menu selections look like: 


IF HookedMenuChoice(theMenu, theItem) = FALSE THEN BEGIN 
CASE theMenu OF 
APPLEMENUID: 
DoAppleMenuCtheItem); 
FILEMENUID: 
DoF i leMenuCtheItem); 
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SPECIALMENUID: 
DoSpecialMenuCtheItem); 
OTHERWISE 
END; 
END; 


where the function HookedMenuChoice is declared in the 
file/unit ‘hooks.p’. It returns false if it DIDN'T handle the menu 
choice, it allows the programmer to *hook' or handle menu 
choices before the applications generic code does and to override 
the generic codes response. For example, the generic code of 
AACK simply puts up a windows, some menus, and allows the 
user to see others of his type on the network and to confirm their 
presence. There is a menu titled "Special" which has items 
labeled “LookUp”, “Confirm” and “Send”. The generic code 
handles the first two items (this can be overridden) but does 
nothing but beep when “Send” is chosen. By changing the code 
in the hooks.p file, you can create an application that does 
something else with AppleTalk, perhaps sending strings through 
the net as was shown in a previous MacTutor article. There is 
obviously a code/speed overhead introduced by using this 
method, but its far more easy to get something to work and to later 
go back and optimize than to start each application from scratch. 
(Maybe I should have called it “ATApp: The Expandable Macin- 
tosh AppleTalk Application"?) 


Bypassing cones (Brand?) Code OR Over- 
Rid’em CowBoy! 


Most of the generic code is trivial stuff to MacTutor readers 
and I have left out some things such as handling DAs which is left 
to the reader as an exercise. The code does use LSPs ability to 
have compiler variables. I declare a compiler option called 
“TALK DEBUG?” and set it to TRUE when I want the compiler 
to include certain debugging code in the app. Basically, the 
generic code does a "SetUp" routine and lets the code from the 
*Hooks" unit do any "SetUp" - i.e. - the generic routine Set- 
UpGlobals does its “SetUps” and then calls the procedure “Set- 
UpHooksGlobals", which lets the Hooks code do its "SetUps". 
Similarly the generic code lets the Hooks code do any Window 
and AppleTalk “SetUps” after it has done its own such "SetUps". 
The generic code also checks to see if the Hooks code has decided 
to take over the duties of taking care of the applications window 
by examining a global Boolean variable called “UserWin- 
dowProcsChanged” which the Hooks code can set to true in its 
“SetUp” code. For example when activating the UserWindow 
the generic code does the following: 


IF UserWindowProcsChanged THEN 
HooksActivateUserWindowProc (Let hook code do its magic) 
SE 


LActivateCT, NemeListHd1); 
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One consequence of this is that even if the Hooks code wants 
to override only one of the procedures that controls the windows 


activation, deactivation, updating, or disposal, it must override ` 


them ALL. You only have to copy and paste the generic code 
from the file main.p into the file hooks.p to mimic the generic 
codes handling of the other procedures though. Forexample, you 
might write an app using AACK which receives/sends messages 
and overrides the way the generic code draws the windows 
contents to draw any received messages at the bottom of the 
window, but it wouldn’t need to override any other of the generic 
codes window handling routines. You could just copy the other 
generic code routines from the file main.p and pasted them into 
the right places in the file hooks.p. 


Generic AppleTalk Code OR AppleTalk is cheap 

The AppleTalk generic code does the following: 

1) calls MPPOpen and then SysEnvirons which returns to us 
among other information, the type of machine we’re running on 
and the version of AppleTalk available. We exit if we’re not 
running on at least a 512КЕ, and if we are, set a boolean variable 
called "NewCallsExist" to true if the AppleTalk driver version 
supports the new AppleTalk calls 

2) opens an ATP socket 

3) calls WaitNextEvent a few times to make sure our dialog 
that lets the user select a name comes up in front and lets the user 
register on the network with a name (1-531 chars) 

4) depending on the setting of a compiler variable called 
"TALK, DEBUG “ tries to call PSetSelfSend, a new AppleTalk 
call which lets you send AppleTalk packets to your own node. 
This is useful if your network consists of one machine as mine 
does, unfortunately this feature is implemented only on machines 
with the drivers with version numbers »- 48, (actually its listed 
as 48 in IM V but 45 in the MPW Assembler Equates, which is 
it Apple?) 

5) then the generic code lets the Hooks unit do any Ap- 
pleTalk “SetUps”, (such as post asynchronous GetRequests if it 
was going to receive requests) 

If all of the above goes well then the generic code sets up its 
Menus, lets the Hooks unit do any of its menu setups, then the 
generic code sets up its window and lets the Hooks unit modify 
that window or set up any of its own and we're off into our event 
loop! 


MultiFinder and AppleTalk OR ASYNC or swim! 

The generic codes event loop calls WaitNextEvent (you 
already know how to check for the presence of WNE so I don't 
do this) and calls a procedure called ““AppleTalkCallChecks” 
before it handles any events. This procedure is going to check for 
any ASYNC calls that may have finished and handle them. For 
example, the generic code calls PLookUpName ASYNChro- 
nously, this allows the user to start a LookUp to see if any other 
users of the same type are on the network, and work on other 
things while the LookUp is begin done. This IS after all is what 
MultiFinder is for! The tricky part of making ASYNC calls is 
knowing when they've finished and taking care of them when 
they do finish. I solve this problem by using Completion 
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Routines and special data structures. I got the idea from Tech 
Note #180 - “MultiFinder Miscellanea”, in which it is suggested 
that applications making ASYNC calls store their AS somewhere 
RELATIVE to the parameter block which they use to make the 
ASYNC calls, so that when their Completion Routines are 
executed they can load the applications A5 and set a global 
variable to indicate that an ASYNC call has finished. I use a 
similar approach. I define the following structure in the file 
"globals.p": 


NameLookUpRec = RECORD 
PbInUse: Boolean; 
CallDone: LongInt; 
xMPPPb: MPPParamBlock; 


END; 


When a call is made using a record of this type the field 
PbInUse is set to TRUE and CallDone is set to zero. The 
Completion Routine that is executed when the call finishes sets 
the CallDone field to -1. 

The routine "AppleTalkCallChecks" (called once through 
each event loop) just checks the CallDone field of the record and 
if itis non-zero we know that an ASYNC call has just completed. 
The advantages of this method are as follows: 

1) the Completion Routine used is VERY simple, as it must 
be since Completion Routines cannot make any calls that affect 
memory, all it does is set the CallDone field to a non-zero value. 
The completion routine is declared in LSP in the following way 
in the file “lowlevelATprocs.p”: 


PROCEDURE InlineRoutine; 
INLINE 


) $213C, $FFFF, $FFFF; ( MOVEA.L #-1,-CAØ) set CallDone 
field 


PROCEDURE XCompletionRoutine; 
(When routine is called Ай = ptr to ParemBlock) 
BEGIN 

In] ineRoutine; 


END; 


2) we dont have to worry about whether our AS is valid when 
our Completion Routine runs 


The drawbacks of using this method are that we must check 
our ASYNC calls EVERY time through our event loop and that 
the parameter blocks we use to make them MUST be global 
variables so that we can check them. 


Using the PREFERRED interface OR Learning to 
AppleTalk all over again 


We'd like to use the (new) ‘preferred’ AppleTalk interface 
because its more robust, and if we're running with the right 
versions of the AppleTalk drivers we can use the new AppleTalk 
calls. Information about the new AppleTalk calls is in IM V (and 
I suppose, in Inside AppleTalk which is available from APDA 
which I dont have). There are two different types of parameter 
blocks defined in the new interface, the ATPParamBlock and the 
MPPParamBlock, and you just fill in the fields necessary for the 
call you want to make and then pass a ptr to the ParamBlock to 
the function you're calling - i.e. - 
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err = PCallName (@ParamBlock, true or false for ASYNC); 


The catch is that when filling out the fields in parameter 
blocks for OLD AppleTalk routines that you call with the NEW 
interface, you use the information from “Calling the AppleTalk 
Manager routines from Assembly Language” from IM II. Look 
at the pages in IM V which describe the new types, it shows which 
fields have to be filled with which values to make a call. Some 
field names have changed though, so be careful, make sure 
you've filled them out right - then check them again! 


New (and Improved?) AppleTalk Calls OR Don't 
LookUp before you leave 

A few new AppleTalk calls are quite useful to us, for 
example, the generic code of AACK does ASYNC LookUps, but 
what happens if the user quits BEFORE the LookUp completes? 
If the application just quit, then sooner or later that ASYNC call 
would complete and the Completion Routine (which is nolonger 
around) would be called and BOOOOM! If we don't have access 
to the new calls then we just have to wait till the ASYNC call 
completes which we can do by: 


while CallDone = 0 do 


2 


, which just waits till a particular call is done before proceed- 
ing. There is however a new call, PKilINBP, which allows us to 
kill pending calls, (but if it fails we will have to wait the call out). 
Note that IM V in some places incorrectly lists which Param- 
Block, ATP or MPP to use, this call requires an MPPParam- 
Block. The generic code also uses the call PSetSelfSend to allow 
the user to receive/send packets to his own node, a feature of the 
new AppleTalk drivers which 1s useful to programmers, but we 
must be careful to restore the state of this flag - i.e. - if it wasn’t 
enabled when we started, then we should disable it when we 
leave. 


The future OR Everybody AppleTalks but no- 
body DOES anything with it 

Should the PConfirmName calls be made ASYNC? ГЇЇ 
leave it to you as an exercise. I’ve already written an application 
(modifying ONLY the file hooks.p) which uses the AACK shell 
to receive/send strings (Str255s actually). If anyone is interested 
in seeing it, let Dave Smith at MacTutor know and I'll write it up, 
its code will be shorter than this article but it may take longer to 
explain. 


Using PSetSelfSend on a Mac Plus OR Ap- 
pleTalking to yourself on a Plus 
I've found a way to get the new AppleTalk drivers running 
on my Mac Plus and I can test my AppleTalk code on my 
‘network of one’ using PSetSelfSend to enable me to send 
packets to myself. Those of you who are thinking, "That's easy, 
just copy the DRVR resources out of the latest System File and 
paste them into the System File you use on your Mac Plus!”, are 
thinking along the wrong lines. The new drivers are in the Mac 
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II ROM and perhaps the SE ROM (I don't have one to test). I'm 
not sure its a good idea to use the new drivers on a Mac Plus, but 
I haven't had any problems with my system (yet). Apple must 
have some reason not to make the new drivers available for the 
Mac Plus so I won't pass this information along unless anyone 
out there is interested and Apple says its OK (you've figured out 
how to do it though, right?). 

I'd like to thank K.S. without whose love and support this 
article would not be possible. 


Listing: globals.p 
unit Globals; 


interface 


uses 
AppleTalk; 


type 
(AppleTalk Types) 
NameLookUpRec = record 
PbInUse: Boolean; 
Са110опе: LongInt; 
xMPPPb: MPPParamBlock; 
end; 


(String Types) 
Str32Hdl = ^Str32Ptr; 
Str32Ptr = ^Str32; 


const 
false; 
true; 


T 


(Constants used ONLY when debugging) 
($IFC TALK. DEBUG ) 

SENDSELF = 1; 
($ENDC) 


(AppleTalk Constants) 
ANYZONE = “x, 
ANYOUB = ‘=’; 
АЅҮМС = Т; 
DOVERIFY = 1; 
LOOKUPBUFFERSIZE = 1023; 
MAXNAMELENGTH = 31; 
MAXTOLOOKUP = 100; 
SYNC = F; 
XNCVERSION = 48; 


(Dialog Constants) 
rABOUTDLOGID = 128; 


rUSERNAMEDLOGID = 129; 
rUSERNAMEITEM = 4; 


(Event Constants) 
MFEVENT = app4Evt; 
RESUMEMASK = 1; 
SUSPENDRESUMEMSG = 1; 


(Menu Constants) 
APPLEMENUID = 128; 
ABOUTITEM = 1; 
FILEMENUID = 129; 
QUITITEM = 1; 
EDITMENUID = 130; 
SPECIALMENUID = 131; 
LOOKUPITEM = 1; 
CONFIRMITEM = 2; 
SENDITEM = 3; 


(String Resource Constants) 
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rAPPUSERNAMESTRID = 128; 
rCHOOSERUSERSTRID = -16096; 
var 


DoneF lag: Boolean; 
DragRect: Rect; 
Evt: EventRecord; 


(Globals used ONLY when debugging) 
($1FC TALK_DEBUG ) 
DebugOnRect: Rect; 
OldSelfFlag: Byte; 
SelfSend0n: Boolean; 
SelfSendOnRect: Rect; 
(ФЕМОС) 


(AppleTalk Globals) 
ConfirmString: Str255; 
ConfirmStringPos: Point; 
Conf irmStringRect: Rect; 
LookUpBuffer: array{®..LOOKUPBUFFERSIZE] of Integer; 
LookUpNamePb: NameLookUpRec; 
LookUpNTT: EntityName; 
LookUpString: Str255; 
LookUpStringPos: Point; 
LookUpStringRect: Rect; 
NBPSNTE: NamesTableEntry; 
NewCallsExist: Boolean; 
UserNTT: EntityName; 
UserSkt: Byte; 


(List Globals) 
ListFremeRect, ListViewRect: Rect; 
MaxRows, NameListLength: Integer; 
NemeListHdl: ListHandle; 


(Event Globals} 
SleepTime: LongInt; 


(Menu Globals} 
AppleMenu, FileMenu, EditMenu, SpecialMenu: MenuHandle; 


(Window Globals} 
TextHeight: Integer; 
UserWindowFontInfo: FontInfo; 
UserWindowProcsChanged: Boolean; 
UserWindowRect: Rect; 
UserWindow, WhichWindow: WindowPtr; 
UserWRec: WindowRecord; 


implementation 
end. 


Listing: lowlevelatprocs.p 
unit LowLevelATProcs; 
interf ace 


uses 
AppleTalk, Globals; 


procedure XCompletionRoutine; 


function NTTExists (ntt2Conf irm: EntitgName; var theAddress: 


AddrBlock): OSErr; 


procedure DrawConf irmString,; 
procedure DrawLookUpStr ing; 


implementation 

procedure InlineRout ine; 

inline 

| ad $FFFF, $FFFF; ( MOVEA.L #-1,-CA®) set CallDone 
field 
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procedure XCompletionRoutine; 
(When routine is called Ай = ptr to ParamBlock) 
begin 
InlineRoutine; 
end; 


function NTTExists (ntt2Conf irm: EntityName; var theAddress: 


AddrBlock): OSErr; 
(This function test whether or not an NTT exists at a 
certain address and) 
( returns its new address if it 'moved/) 
var 
err: OSErr; 
localMPPPb: MPPParamBlock; 
begin 
with localMPPPb do 
begin 
ioCompletion := nil; 
($IFC TALK_DEBUG } 
interval := 6; 


count := 2; 
($ELSC) 

interval := 10; 

count := 10; 
($ENDC) 


entityPtr := @ntt2Confirm; (NTT to confirm) 
conf irmAddr := theAddress; (address to confirm) 


err := PConf irmNameC@localMPPPb, SYNC); 
NTTExists := err; 
if err = nbpConfDiff then 
(If the NTT ‘moved’ then return its new address) 
theAddress.aSocket := newSocket; 
end; 
end; 


procedure DrawConf irmString; 
(This proc draws the result of the last Conf irmName call) 
{It assumes that the current port is the user window) 
begin 
with ConfirmStringPos do 
begin 
EraseRect (Conf irmStr ingRect); 
Movelo(h, v); 
DrawString( ‘Confirm Status = ”); 
DrawString(ConfirmString); 
end; 
end; 


procedure DrawLookUpString; 
(This proc draws the result of the last LookUpName call) 
(It assumes that the current port is the user window) 
begin 
with LookUpStringPos do 
begin 
EraseRect(LookUpStringRect); 
Movelo(h, v); 
DrawString( ‘LookUp Status = 7). 
DrawString(LookUpString); 
end; 
end; 


end. 

Listing: hooks.p 
unit Hooks; 
interface 


uses 
AppleTalk, Globals, LowLevelATProcs; 


const 
USERTYPE = ‘NATH’; 


procedure SetUpHooksGlobals; 
procedure SetUpHooksMenus ; 


function HookedMenuChoice (menu, item: Integer): Boolean; 


procedure HooksAct ivateUserW indowProc; 
procedure HooksCloseUserWindowProc; 
procedure HooksDeact ivateUserWindowProc; 
procedure HooksUpdateUserWindowProc; 
procedure HooksUserWindowDoContentHi t; 


procedure ActivateHooksWindow CtheWIndow: WindowPtr); 
procedure CloseHooksWindows; 

procedure DeactivateHooksWindow CtheWIndow: WindowPtr); 
procedure DoHooksWindowContentHit; 

function SetUpHooksWindows: Boolean; 

procedure UpdateHooksWindow CtheWIndow: WindowPtr); 


procedure HooksAppleTalkCallChecks; 

function HooksAppleTalkGlobalsSetUp: Boolean; 
procedure HooksCloseUpAppleTalk; 

function HooksRegistered: Boolean; 


implementation 


procedure SetUpHooksGlobals; 

(This proc allows the hook code to init its globals) 
begin 

end; 


procedure SetUpHooksMenus; 

(This proc allows the hook code to init its menus) 
begin 

end; 


function HookedMenuChoice (menu, item: Integer): Boolean; 

(This proc allows the hook code to override menu choices 
which the generic code) 

(would normally handle, it returns T if it overrode a menu 
choice) 

begin 

(Assume we're not handling the menu choice) 

HookedMenuChoice := F; 
end; 


procedure HooksActivateUserWindowProc; 

(This proc is used to override the generic codes activation 
of the UserWindow) 

begin 

end; 


procedure HooksCloseUserWindowProc; 

(This proc is used to override the generic codes closing of 
the UserWindow) 

begin 

end; 


procedure HooksDeact ivateUserWindowProc; 

(This proc is used to override the generic codes deactiva- 
tion of the UserWindow) 

begin 

end; 


procedure HooksUpdateUserWindowProc; 

(This proc is used to override the generic codes updating of 
the UserWindow) 

begin 

end; 


procedure HooksUserWindowDoContentHit; 
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(This proc is used to override the generic codes handling of 
mouse hits) 

(in the UserWindow) 

begin 

end; 


procedure ActivateHooksWindow CtheWIndow: WindowPtr); 

(This proc is used to activate any windows the hook code 
created) 

begin 

end; 


procedure CloseHooksWindows; 

(proc is used to close any windows the hook code created) 
begin 

end; 


procedure DeactivateHooksWindow CtheWIndow: WindowPtr); 
(proc is used to deactivate any windows hook code created) 
begin 

end; 


procedure DoHooksWindowContentHit; 

(This proc is used to handle mouse hits in any windows the 
hook code created) 

begin 

end; 


function SetUpHooksWindows: Boolean; 

(proc is used to setup windows hook code wants to create) 

(end it allows the hook code to set the UserWin- 
dowProcsChanged global) 

(it returns T if it succeeds) 

begin 

(Assume error) 

SetUpHooksWindows := F; 


(Set to false to show that we dont change anu of the 
UserWindow procs) 
UserWindowProcsChanged := F; 


(Return T since we succeeded) 
SetUpHooksWindows := T; 
end; 


procedure UpdateHooksWindow (theWIndow: WindowPtr); 

(proc is used to update anu windows the hook code created) 
begin 

end; 


procedure HooksAppleTalkCallChecks; 

(proc is used to check any ASYNC AppleTalk calls hook code 
made) 

begin 

end; 


function HooksAppleTalkGlobalsSetUp: Boolean; 
(This proc does any AppleTalk setups hook needs to make, it) 
(returns T if it succeeds) 
begin 
(Assume error) 
HooksAppleTalkGlobalsSetUp := F; 


(Return T since we succeeded) 
HooksApplelalkGlobalsSetUp := T; 
end; 


procedure HooksCloseUpAppleTalk; 

(proc does any AppleTalk closeups the hook needs to make) 
begin 

end; 


function HooksRegistered: Boolean; 
(This allows the hook code to do any AppleTalk calls its 
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needs to make) 
(after the User had registered. IL returns T if it 
succeed) 
begin 
(Assume error) 
HooksRegistered := F; 
(Return T since we succeeded) 
HooksRegistered := T; 
end; 
end. 


Listing: main.p 
program AACK; 


uses 
Applelalk, Globals, LowLevelATProcs, Hooks; 


procedure Crash; 
(This proc is called if we crash) 
begin 
ExitToShe11; 
end; 


procedure SetUpToolbox; 
(This proc inits the Mac toolbox) 
begin 
MaxApp1Zone; 
MoreMasters; 
MoreMasters; 
MoreMasters; 
MoreMasters; 
InitGraf CéthePort); 
InitFonts; 
InitWindows; 
FlushEventsCeveryEvent, 0); 
InitMenus; 
TEInit; 
InitDialogsC@Crash); 
InitCursor ; 
end; 


procedure SetUpGlobals; 
(This proc does any app global inits) 
begin 

DoneFlag := F; 


DragRect := screenBits.bounds; 
with DragRect do 


begin 
top := top + 20; (NOTE! we really should use the 
mbarhe ight} 
left := left + 4; . 
bottom := bottom - 4; 
right := right - 4; 
end; 


(Assume the new calls dont exist) 
NewCallsExist := F; 


SleepTime := 19; 


($IFC TALK_DEBUG ) 
with DebugOnRect do 
begin 


with SelfSendOnRect do 
begin 
top := 5; 
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left := 0; 
bottom := 9; 
right := 4; 
end; 
($ENDC) 
(Allow setup of any globals from the Hooks unit) 
Se tUpHooksGlobals; 
end; 


procedure SetUpMenus; 

(This proc sets upthe generic codes menus} 

begin 
AppleMenu := GetMenuCAPPLEMENUID); 
AddResMenuCAppleMenu, ‘DRVR’); 
InsertMenuCAppleMenu, 0); 


FileMenu := GetMenu(FILEMENUID); 
InsertMenuCF ileMenu, 0); 


EditMenu := GetMenuCEDITMENUID); 
InsertMenuCEditMenu, 0); 


SpecialMenu := GetMenuCSPECIALMENUID); 
InsertMenu(SpecialMenu, 0); 


(Allow setup of any menus from the Hooks unit) 
Se tUpHooksMenus ; 


DrawMenuBar ; 
end; 


procedure CloseWindows; 

(This proc closes the apps windows) 

begin 

(Allow closing of any windows from the Hooks unit) 
CloseHooksWindows; 


if UserWindowProcsChanged then 


HooksCloseUserWindowProc (Let the hook code do it magic) 


else 
begin 
LDisposeCNameL istHd1); 
CloseW indow(UserWindow); 
end; 
end; 


function GotWindows: Boolean; 
(This code sets up the apps windows, it returns T) 
(if it succeeds} 
var 
theCell: Cell; 
dBounds: Rect; 
begin 
(Assume we fail) 
GotWindows := F; 


UserWindowRect := DragRect; 
with UserWindowRect do 
begin 
top := top + 20; 
left := left + 4; 
bottom := top + 200; 
right := left + 225; 
end; 


(Get the UserWindow) 
UserWindow := NewWindow(@UserWRec, UserWindowRect, 
UserNTT.objStr, F, noGrowDocProc, WindowPtr(-1), T, 0); 
if UserWIndow © nil then 
begin 

se tPor t CUserW indow); 
ClipRect(UserWindow*.portRect); 
TextFont (monaco); 
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TextSize(9); 
GetFontInfo(UserWindowFontInfo); 
with UserWindowFontInfo do 

TextHeight := ascent + descent + leading; 


(Set the # of rows to displau in our list) 
MaxRows := 10; 


(Set the current list length to 0) 
| NameListLength := 0; 


with dBounds do 


begin 
top := 0; 
left := 0; 
bottom := NameListLength; (no rows for now) 
right := 1; (one column) 
end; 
theCell.h := 0; 
theCell.v := 0; 


(Set up the lists view rect) 
with ListViewRect do 


left := 10; 


ListViewRect.top; 
right := (32 * CharWidth(’w’)) + 8; 
end; 


(Tru to get a ListHandle) 
NameListHdl := LNew(ListViewRect, dBounds, theCell, 
@, UserWindow, T, F, F, T); 


if NameListHd] = nil then 
M failed to get a ListHandle so close UserWindow and 
exit 
CloseWindowCUserWindow) 
else 
begin 
(We got the ListHandle, allow only one selection at a time 
from it) 
NemeListHdl^^.selFlags := LOnluOne; 


(Set up a rect to put a frame around our list) 
ListFrameRect := ListViewRect; 
with ListFrameRect do 
begin 

top := top - 1; 
left := left - 1; 
bottom := bottom + 1; 
right := right + 16; 


(Set up the pos to draw the LookUpName results at) 
with LookUpStringPos do 


begin 

h := left; 

v := bottom + TextHeight; 
end; 


(Set up the pos to draw the ConfirmName results at) 
with ConfirmStringPos do 


begin 
h := left; 
v := LookUpStringPos.v + TextHeight; 
end; 
end; 


(Set up the rect to erase the old LookUpName result) 
with LookUpStringRect do 
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begin 
top := ListFrameRect.bottom + 1; 
left := UserWindow* .portRect. left; 
bottom := LookUpStringPos.v + 
UserWindowFontInfo.descent; 
right := UserWindow^ .portRect right; 
end; 


(Set up the rect to erase the old Conf irmName result) 
with Conf irmStringRect do 
begin 
top := LookUpStringRect.bottom + 1; 
left := UserWindow^ .portRect . left; 
bottom := ConfirmStringPos.v + 
UserWindowFontInfo.descent; 
right := UserWindow^ .portRect .right; 
end; 


(Set to false, assume no hook code override) 
UserWindowProcsChanged := F; 


(Allow setup of anu windows from the Hooks unit) 
if SetUpHooksWindows = T then 
begin 
ShowWindow(UserWindow); 
(We succeeded! Return T) 
GotWindows := T; 
end 
else 
begin 
(SetUpHooksWindows failed) 
LDisposeCNameL istHd12); 
CloseWindowCUserWindow?; 
end; 
end; 
end; 
end; 


procedure DoDrag; 
(This code drags windows around) 
begin 
DragWindow(WhichWindow, Evt.where, DragRect); 
end; 


procedure ActivateUserWindow; 
(This code activates the apps windows) 
begin 

if UserWindowProcsChanged then 


HooksActivateUserWindowProc (Let hook code do its magic) 


else 
LActivateCT, NameListHd1); 
end; 


procedure DeactivateUserWindow; 
(This code deactivates the apps windows) 
begin 

if UserWindowProcsChanged then 


HooksDeactivateUserWindowProc (Let the hook code do its 


magic) 
else 
LActivateCF, NameListHd1); 
end; 


procedure UpdateNameL ist; 


(This code updates the list of names in the NameListHandle) 


var 
theAddress: AddrBlock; 
theCe11: Cell; 
theNTT: EntityName; 
theNum: Integer; 
err: OSErr; 
thePtr: Ptr; 

begin 

with LookUpNamePb do 
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begin 
if NameListLength € @ then 
LDelRow(NemeListLength, Ø, NameListHd]); (Delete 
any rows present) 
NemeListLength := xMPPPb.numGotten; (Get the new # of 
rows needed) 
if NameListLength О 0 then 
begin 
theNum := LAddRowCNemeL istLength, Ø, 
NameListHd12; (Add the # of new rows) 
theCell.h := 0; 
for theNum := 1 to NameListLength do 
begin 
err := NBPExtract(@LookUpBuffer, NameLis- 
tLength, theNum, theNTT, theAddress); {extract a name) 
if err = noErr then 
begin 
theCell.v := theNum - 1; (Cells are 
numbered starting from zero so bump row # back) 


thePtr := PtrCORD4C@theNTT.objStr) + 1); 


(Pt to the data) 
LSetCellCthePtr, length(theNTT.objStr), 
theCell, NameListHd1); (Set the cells data) 
end; 
end; 
(Select the first row) 
theCell.h := 0; 
theCell.v := Ø; 
LSetSelect(T, theCell, NameListHd1); 
end; 
end; 
end; 


procedure UpdateUserWindow; 
(This code updates the UserWindow) 
var 
theRgn: RgnHandle; 
begin 
if UserWindowProcsChanged then 
HooksUpdateUserWindowProc (Let hook code do its magic} 
else 
begin 
($IFC TALK.DEBUG ) 
ForeColor(redColor); 
FillRect(DebugOnRect, black); 


if SelfSendOn then 
begin 
ForeColor(cyanColor); 
FillRectCSelfSendOnRect, black); 
end 
else 
begin : 
ForeColor(cyanColor); 
FrameRect(SelfSend0nRect); 


end; 

ForeColor(blackColor); 

($ENDC) 
FrameRect(ListFrameRect); (Put a frame around list) 
theRgn := UserWindow^.visRgn; 
LUpdateCtheRgn, NameListHd1); (Update the list) 
DrawLookUpString; (Draw in last LookUpName result) 
DrawConfirmString; (Draw in last ConfirmName result) 

end; 
end; 


procedure DoActivate; 
(This code activates any app windows) 
var 
theWindow: WindowPtr; 
begin 
theWindow := WindowPtr(Evt.message); 


@ The Best of MacTutor, Vol. 5 


SetPortCtheWindow); 
if BAndCactiveFlag, Evt.modifiers) € 0 then 
begin 
if theWindow = UserWindow then 
ActivateUserWindow 
else 
ActivateHooksWindow( theWindow); (Let the hook code 
activate its windows) 


end 
else 
begin 
if theWindow = UserWindow then 
DeactivateUserWindow 
else 


DeactivateHooksWindowCtheWindow2; (Let the hook 
code deactivate its windows) 
end; 
end; 


procedure DoUpdate; 
(This proc does updates of app windows) 
var 
oldPort: GrafPtr; 
theWindow: WindowPtr; 
begin 
GetPortColdPort); 


theWindow := WindowPtr(Evt.message); 
SetPortCtheWindow); 


BeginUpdateCtheWindow); 


if theWindow = UserWindow then 
UpdateUserWindow 
else 
UpdateHooksWindow(theWindow); (Let the hook code update 
any of its windows) 


EndUpdate( theWindow); 


SetPortColdPort); 
end; 


procedure DoMFEvent; 
(code handles MultiFinder events such as deac/activation of) 
(windows upon suspend/resume events) 
var 
theWindow: WindowPtr; 
begin 
theWindow := FrontWindow; 
case BSR(Evt.message, 24) of (high byte of message) 
SUSPENDRESUMEMSG : 
begin 
if BAndCEvt.message, RESUMEMASK) <> 0 then 
begin 
SleepTime := 10; 
se tPor t( theWindow); 
if theWindow = UserWindow then 
ActivateUserWindow 
else 
ActiveteHooksWindowCtheWindow); (Let the 


hook code activate its windows) 


end 
else 
begin 
SleepTime := 60; 
setPor t( theWindow); 
if theWindow = UserWindow then 
DeactivateUserWindow 
else 
DeactivateHooksWindowCtheWindow2; (Let the 


hook code deactivate its windows) 


end; 
end; 
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otherwise 
end; 
end; 


function UserRegistered: Boolean; 
(This proc lets User register on the network, it return T) 
(T if it succeeds) 
label 
100; 
var 
localATPPb: ATPParemBlock; 
theDialog: DialogPtr; 
theDRec: DialogRecord; 
oldPort: GrefPtr; 
item: Handle; 
itemHit: Integer; 
localMPPPb: MPPParamBlock; 
err: OSErr; 
itemRect: Rect; 
theStr32Hdl: Str32Hd1; 
theString: Str255; 
begin 
(Assume we fail) 
UserRegistered := F; 


(Get the string entered in the ‘Chooser ’} 
theStr32Hdl := Str32Hd1(GetResource( ‘STR ', rCHOOSERUSER- 
STRID)); 


(If there is no default user name from the chooser, then set 
theString to the) 
(null string) 
if theStr32Hdl = nil then 
theString := °’; 


GetPortColdPort); 


theDialog := GetNewDialogCrUSERNAMEDLOGID, @theDRec, 
WindowPtr(- 122; 
SetPortCtheDialog?; 


ShowWindow( theDialog); 


100 : 
if theStr32Hdl © nil then 
begin 
HLockCHandle(CtheStr32Hdl)2; 
theString := theStr32Hdl^^; (theString = the chooser 
string) 
HUnlockCHandleCtheStr32Hd1)); 
end; 


(Show theString in the dialog and select it) 
GetDItemCtheDialog, rUSERNAMEITEM, itemHit, item, 
itemRect); 
SetITextCitem, theString); 
SellTextCtheDialog, rUSERNAMEITEM, 9, 32767); 


(Loop until OK or Cancel is hit) 
repeat 
ModalDialog(nil, itemHit) 
until CCitemHit = ok) or CitemHit = cancel)); 


if itemHit = ok then 
begin 
GetDItemCtheDialog, rUSERNAMEITEM, itemHit, item, 
itemRect); 
GetITextCitem, theString); 
itemHit := lengthCtheString); 
if CitemHit > Ø) and CitemHit <= MAXNAMELENGTH) then 
begin 
(theString must be > Ø but < 32) 
(First try to open a socket) 
with localATPPb do 
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begin 
ioCompletion := nil; 
atpSocket := 0; 
with addrBlock do 


begin 
aNet := 0; 
aNode := 0; 
aSocket := 0; 
end; 


end; 


err := POpenATPSktC@localATPPb, SYNC); 
if err = noErr then 
begin 
UserSkt := localATPPb.atpSocket; (Save the 
socket #) 
(Try to register the user on the network} 
NBPSetEntityC@UserNTT, theString, USERTYPE, 
ANYZONE); 
NBPSetNTEC@NBPSNTE, UserNTT.objStr, USER- 
TYPE, ANYZONE, UserSkt); (Set up the nte that NBP wants} 


with localMPPPb do 

begin 
ioCompletion := nil; 
interval := 3; 
count := 3; 
entituPtr :- @NBPSNTE; 
verifyFlag := DOVERIFY; (Make sure we 

register with a unique name} 
end; 


err := PRegisterNameC@localMPPPb, SYNC); 
if err = noErr then 
begin 
(We registered successfully!) 
UserRegistered := HooksRegistered; (Let 
the hook code do its magic) 


($1FC TALK_DEBUG ) 
(Enable self sending if the new calls exist) 
if NewCallsExist then 
begin 
localMPPPb .newSelfFlag := SENDSELF; 
err := PSetSelfSend(81localMPPPb, 
SYNC); 
if err = noErr then 
begin 
OldSelfFlag := 
localMPPPb.oldSelfFlag; (Save the old self flag state) 
SelfSendOn := T; (Mark our 
selfsend flag as on) 
end 
else 
SelfSendOn := F; (We failed, mark 
our selfsend flag as off) 
end 
else 
SelfSendOn := F; (Mark our selfsend 
flag as off) 
($ENDC) 
end 
else 
begin 
(PRegisterName failed) 
(Close the UserSkt) 
localATPPb.atpSocket := UserSkt; 
err :- PCloseATPSktC81ocalATPPb, SYNC); 
end; 
end; 
end 
else 
(User didn’t enter a valid string) 
goto 100; 
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end; 


(Close the dialog and return the result) 
CloseDialog(theDialog); 
SetPort(oldPort); 

end; 


function AppleTalkOK: Boolean; 
(This proc makes sure we're running on at least a 512KE) 
(, it returns T if so and checks to see if the new calls 
exist) 
var 
err: OSErr; 
theWorld: SusEnvRec; 
begin 
(Assume we failed) 
AppleTalkOK := F; 


err := MPPOpen; (Open Applelalk) 
if err = noErr then 
begin 
err := SusEnvirons(1, theWorld); 
if err = noErr then 
begin 
with theWorld do 
begin 
if machineType >= env512KE then 
begin 
(Ме ve got at least а 512KE) 
if atDrvrVersNum >= XNCVERSION then 
(We've got the new calls} 
NewCallsExist := T; 
AppleTalkOK := UserRegistered; (Let the 
user try to register) 
end; 
end; 
end; 
end; 
end; 


procedure AppleTalkCallChecks; 
(This proc checks to see if any of ASYNC calls have fin- 


ished) 
var 
oldPort: GrafPtr; 
begin 
with LookUpNamePb do 
begin 
if Са110опе o 0 then 
begin 
PbInUse := F; 
CallDone := 0; 
GetPort(oldPort); 
SetPort(UserWindow); 
UpdateNameL ist; 
LookUpString := ‘done’; 
DrawLookUpStr ing; 
SetPortColdPort); 
end; 
end; 


(Allow any AppleTalk call checks in the Hooks unit) 
HooksAppleTalkCallChecks; 
end; 


procedure CloseUpAppleTalk; 
(This proc closes up the apps AppleTalk socket lets hook) 
(code cleanup anything it did with AppleTalk) 
var 
localATPPb: ATPParamB lock ; 
localMPPPb: MPPParamBlock; 
err: OSErr; 
begin 
(A LookUp call may not have finished, if new calls exist) 
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(then KillNBP it, if not then we must wait till it fin- 
ishes.) 
with LookUpNamePb do 
begin 
if PbInUse then 
begin 
(There is a LookUpName in progress) 
if NewCallsExist then 
begin 
(We've got the new calls so we can kill it) 
with localMPPPb do 
begin 
ioCompletion := nil; 
NKi11QE1 := @LookUpNamePb . xMPPPb; 


end; 
err := PKil]NBP(@localMPPPb, SYNC); 
if err © noErr then 
begin | 
(We failed to KillNBP the LookUp so we’ll just loop till 
the LookUp is done) 
(NOTE that we test the CallDone field since its changed bu 
the completion routine, NOT) 
(the PbInUse field) 
while LookUpNamePb.CallDone = Ø do 
7 
end; 
end 
else 
(Тһе new calls dont exist so we’ll just loop till the 
LookUp is done) 
(NOTE that we test the CallDone field since its changed bu 
the completion routine, NOT) 
(the PbInUse field) 
while LookUpNamePb.CallDone = 0 do 
4 
end; 
end; 


(Allow Hooks unit to closeup any AppleTalk calls it made) 
HooksC loseUpApp leTalk; 


(Close the UserSkt) 
localATPPb.atpSocket :» UserSkt; 
err := PCloseATPSktC@localATPPb, SYNC); 
if err «> noErr then 
SysBeep( 1); 


(Remove the users name from the network} 
localMPPPb.entityPtr := @UserNTT; 
err := PRemoveName(@localMPPPb, SYNC); 
if err € noErr then 
SysBeep( 1); 


($IFC TALK_DEBUG ) 
(Restore the SelfSendFlag to its former state) 
if NewCallsExist then 
begin 
if SelfSendOn then 
begin 
if OldSelfFlag = @ then 
begin 
(Turn it off if it wasn't on before) 
localMPPPb.newSelfFlag := OldSelfFlag; 
err := PSetSelfSend(@localMPPPb, SYNC); 
end; 
end; 
end; 
($ENDC) 
end; 


function AppleTalkGlobalsSetUp: Boolean; 
(This proc inits any app AppleTalk globals) 
begin 

(Assume error} 
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AppleTalkGlobalsSetUp : 


" 
E 
`. 


with LookUpNamePb do 
begin 
PbInUse := F; 
CallDone := 0; 
end; 


ConfirmString := ‘never done’; 
LookUpString := ‘never done’; 


(Allow setup of AppleTalk globals from the Hooks unit} 
if HooksAppleTalkGlobalsSetUp then 
AppleTalkGlobalsSetUp := T; 

end; 


procedure DoWNEs; 


(Do a few WNEs to make sure our dialog comes up in front) 


var 
theResult: Boolean; 
begin 
theResult := WaitNextEventCevergEvent, Evt, 0, nil); 
theResult := WaitNextEventCeveryEvent, Evt, 0, nil); 
theResult := WaitNextEventCeveryEvent, Evt, 8, nil); 
theResult := WeitNextEventCeveryEvent, Evt, 0, nil); 
theResult := WaitNextEventCeveryEvent, Evt, 8, nil); 
end; 


procedure DoAbout; 
(This proc shows our About box) 
var 
theDialog: DialogPtr; 
theDRec: DialogRecord; 
oldPort: GrafPtr; 
itemhit: Integer; 
begin 
GetPort(oldPort); 


theDialog := GetNewDialog(rABOUTDLOGID, @theDRec, Win- 
dowPtr(-1)); 

SetPort(theDialog); 

ShowWindow(theDialog); 


repeat 
ModalDialog(nil, itemHit) 
until CitemHit = ok); 


CloseDialog(theDialog); 


SetPortColdPort); 
end; 


procedure DoAppleMenu (item: Integer); 
(This proc handles the Apple Menu) 
begin 
case item of 
ABOUTITEM: 
DoAbout ; 
otherwise 
end; 
end; 


procedure DoFileMenu Citem: Integer); 
(This proc handles the File enu) 
begin 
case item of 
QUITITEM: 
DoneFlag := T; 
otherwise 
end; 
end; 


procedure DoLookUp; 
(This proc does an ASYNC LookUpName) 
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var 
oldPort: GrafPtr; 
err: OSErr; 
begin 
with LookUpNamePb do 
begin 
if PbInUse = F then 
begin 


(If we're not already doing one) 
NBPSetEntityC@LookUpNTT, АМҮОЈВ, USERTYPE, 
ANYZONE); {Setup who to look for) 


CallDone :- 0; 


with xMPPPb do 
begin 
ioCompletion := @XCompletionRoutine; 
($IFC TALK_DEBUG } 
interval := 2; 


count := 3; 
($ELSC) 

interval := 6; 

count := 5; 
($ENDC) 


entityPtr := &LookUpNTT; 
retBuffPtr := @LookUpBuffer; 
retBuffSize := sizeof (LookUpBuffer); 
maxToGet := MAXTOLOOKUP; 

end; 


err := PLookUpNameC@xMPPPb, ASYNC); 
(Show the LookUps progress} 
GetPortColdPort); 
SetPortCUserWindow2; 
if err = noErr then 
begin 
PbInUse := T; 
LookUpString := “in progress”; 
end 
else 
LookUpString := ‘error’; 
DrawLookUpStr ing; 
SetPortColdPort); 
end; 
end; 
end; 


procedure DoConf irm; 
(This proc does a SYNC Conf irmName) 
var 
theAddress: AddrBlock; 
nameIsSelected: Boolean; 
theCe11: Cell; 
extractedNTT, ntt2Conf irm: EntityName; 
oldPort: GrefPtr; 
err: 05Егг; 
begin 
if LookUpNamePb.PbInUse then 
begin 
(Dont try to Conf irmName while а LookUp is in progress) 
GetPortColdPort); 
SetPortCUserWindow); 
ConfirmString := ‘LookUp in progress’; 
DrawConf irmString; 
SetPortColdPort); 
end 
else 
begin 
theCell.h 0; 
theCell.v 0; 
namelsSelected := LGetSelect(T, theCell, 
NameListHd1); (Get the selected list item) 


if namelsSelected then 
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begin 


(Onlu do a Confirm if an item in the list is selected) 


theCell.v := theCell.v + 1; 


err := NBPExtractCéLookUpBuf fer, NameListLength, 
theCell.v, extractedNTT, theAddress); (Get the address) 


if err = noErr then 
begin 
NBPSetEnt i tyCéntt2Conf irm, 
extractedNTT.objStr, extractedNTT.typeStr, 
extractedNTT .zoneStr); 


err := NTTExistsCntt2Conf irm, theAddress); 


(Check if the NTT exists) 
(Show the result of the Conf irmName) 
GetPortColdPort); 
SetPor t(UserW indow); 
if err = noErr then 
ConfirmString := ‘confirmed’ 
else 
begin 
case err of 
nbpNoConf irm: 
Conf irmString : 
nbpConfDiff : 
Conf irmString 
otherwise 
Conf irmString 
end; 
end; 
DrawConf irmString; 
SetPortColdPort); 
end; 
end; 


‘moved’; 


‘error’; 


end; 
end; 


procedure DoSendRequest; 


(This is the generic codes response to choosing ‘Send’} 


begin 
SysBeep( 1); 
end; 


procedure DoSpecialMenu (item: Integer); 
(This proc handles the Special Menu} 
begin 
case item of 
LOOKUPITEM: 
DoLookUp ; 
CONF IRMITEM: 
DoConf irm; 
SENDITEM: 
DoSendRequest; 
otherwise 
end; 
end; 


procedure DoMenu (menuChoice: LongInt); 
(This proc handles menu selections) 


var 
theItem, theMenu: Integer; 
begin 
theItem := LoWord(menuChoice); 
theMenu := HiWord(menuChoice); 


if HookedMenuChoiceCtheMenu, theItem) = F then 
begin 


(Hook code didn’t handle menu choice so generic code must} 


case theMenu of 
APPLEMENUID : 
DoAppleMenu( the! tem); 
FILEMENUID: 
DoF i JeMenuC( the! tem); 
SPECIALMENUID: 
DoSpecialMenuCtheItem); 
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‘can’’t confirm '; 


otherwise 
end; 
end; 


HiliteMenuC2); 
end; 


procedure DoKDown; 
(This code handles keydowns) 
type 
Trick = packed record 
case Boolean of 
TRUE: € 
long: Longint 


); 
FALSE: ( 

chr3, chr2, chr1, chr: Char 
) 


end; 
var 
charCode: Char; 
trickVar: Trick; 
begin 
trickVar.long := Evt.message; 
charCode :- trickVar.chr0; 
(IF BitAnd(Evt.modifiers, CmdKeu) = CmdKeu THEN) 
if BAnd(CmdKeu, Evt.modifiers) € 0 then 
DoMenu(MenuKey(charCode 22; 
end; 


procedure DoContentHit; 
(This code handles hits in the apps windows) 
var 
clickResult: Boolean; 
localPt: Point; 
begin 
if WhichWindow € FrontWindow then 
SelectWindow(WhichWindow) 
else 
begin 
localPt := Evt.where; 
SetPor tCWh ichWindow); 
if WhichWindow = UserWindow then 
begin 
if UserWindowProcsChanged then 


HooksUserWindowDoContentHit (Let the hook code 


do its magic) 
else 
begin 
Global ToLocal ClocalPt); 


if PtinRectClocalPt, ListFrameRect) then 


clickResult := LClickClocalPt, 
Evt.modifiers, NemeListHdl2; 
end; 
end 
else 
(A hook window was hit, let it handle it) 
DoHooksW indowContentHit; 
end; 
end; 


procedure DoMDown; 
(This code handles mouse down events) 
var 
theResult: Integer; 
begin 
theResult := FindWindowCEvt.where, WhichWindow); 
case theResult of 
inDrag: 
DoDrag; 
inMenuBar : 
DoMenu(MenuSe lectCEvt .where2); 
inContent : 
DoContentHit; 
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otherwise 
end; 
end; 


procedure MainLoop; 
(This is the apps event loop) 


var 
theResult: Boolean; 
begin 
while DoneFlag = F do 
begin 


theResult := WaitNextEventCeveryEvent, Evt, Sleep- 
Time, nil); 
AppleTalkCallChecks; (Check to see if any ASYNC calls 
completed) 
if theResult then 
begin 
(Handle any event) 
case Evt.what of 
keyDown: 
DoKDown; 
mouseDown: 
DoMDown ; 
activateEvt: 
DoActivate; 
updateEvt: 
DoUpdate; 
MFEVENT: 
DoMFEvent; 
otherwise 
end; 
end; 
end; 
end; 


($1-) 
(We do our own inits) 
begin 
SetUpToolbox; 
SetUpGlobals; 
DoWNEs ; 


if AppleTalkOK then 
begin 
SetUpMenus; 


if GotWindows then 
begin 


if AppleTalkGlobalsSetUp then 
begin 


MainLoop; 


CloseWindows; 
end; 
end; 


CloseUpAppleTalk; 
end; 


ExitToShe11; 
end. 


Listing: resources.r 


resource ‘SIZE’ (-1) ( 
dontSaveScreen, 
acceptSuspendResumeEvents, 
disableOptionSwitch, 
canBackground, 
multiF inderAware, 
81920, 
81920 
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); 


resource 'DITL^ (128, purgeable, preload) ( 
( /* array DITLarray: 3 elements */ 
/* [1] */ 
(130, 134, 150, 213), 
Button ( 
enabled, 
“Continue” 


}, 
/* [2] */ 
(8, 63, 26, 298), 
StaticText ( 
disabled, 
“AACK - Version 1.1 - by Ajay Nath” 


), 
/* (3) */ 
(56, 80, 74, 266), 
StaticText ( 
enabled, 
) “Copyright € 1989 Ajay Nath” 


) 
); 


resource 'DITL^ (129, purgeable, preload) ( 
( /* array DITLarrau: 4 elements */ 
/* [1] */ 
(89, 23, 109, 83), 
Button ( 
enabled, 
“ОК” 


), 
/* [2] */ 
(90, 250, 110, 310), 
Button ( 
enabled, 
“Cancel” 


), 

/* [3] */ 

(6, 10, 41, 319), 

StaticText ( 
disabled, 
“Enter а name (31 characters ог less) to ^ 
“use on the network” 


), 

/* [4) */ 

(52, 16, 72, 317), 

EditText ( 
enabled, 


) 
) 
); 


resource 'DLOG^ (128, purgeable, preload) ( 
(36, 146, 204, 490), 
dBoxProc, 
invisible, 
noGoAway, 
0x0, 
128, 


); 


resource 'DLOG^ (129, purgeable, preload) ( 
(36, 150, 160, 482), 
dBoxProc, 
invisible, 
noGoAway, 
0x0, 
129, 
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resource ‘MENU’ (128, preload) ( 
128, 
textMenuProc, 
QxTFFFFFFD, 
enabled, 
apple, 
( /* array: 2 elements */ 
/* (1) */ 
"About AACK..", noIcon, 4” *", plain, 
/* [2] */ 
*-*, noIcon, *^, ““ plain 
) 
); 


resource 'MENU^ (129, preload) ( 
129, 
textMenuProc, 
allEnabled, 
enabled, 
“File, 
( /* array: 1 elements */ 
/* [1] */ 
“Quit”, noIcon, "Q^, "", plain 


); 


resource ‘MENU’ (130, preload) ( 
130, 
textMenuProc, 
OxTFFFFFFD, 
enabled, 


); 


"Edit", 


( 


) 


/* erray: 6 elements */ 

/* [1] */ 

"Undo", noIcon, “Z”, "^, plain, 
/* [2] */ 

*-*, noIcon, “”, *", plain, 

/* [3] */ 

“Cut”, noIcon, "X^, "^, plain, 
/* (4) */ 

“Сору”, noIcon, "C", "", plain, 
/* [5] */ 

"Paste", noIcon, "V", “”, plain, 
/* [6] */ 

“Clear”, noIcon, "^", *", plain 


resource ‘MENU’ (131, preload) ( 
131, 

textMenuProc, 

allEnabled, 

enabled, 

“Special”, 

( /* array: 3 elements */ 


/* [1] */ 


“LookUp”, noIcon, “L”, *", plain, 


/* [2] */ 


“Confirm”, noIcon, “Ғ”, *", plain, 


/* [3] */ 
"Send", поІсоп, "S", *", plain 
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Color Workshop 
Capture Color Icons 


Color Icons: Editor and cicnCapture 

This month’s Color Quickdraw column consists of less talk 
and more code. In the last column, the building block data 
structures needed in order to use and understand color icons were 
discussed. A new Rez/Derez resource source template was given 
that allowed easier creation of ‘cicn’ resource (Color Icon tem- 
plate resource). While the template is helpful in leaming and 
understanding color icons, and is an excellent way to present 
color icons on the written page, most users would prefer to use 
some graphic base tool to create a color icon. This column 
contains a quick review of the two color icon editors freely 
available to the development community. Then, the column will 
present this months source code, ‘cicnCapture’, a FKEY utility 
designed to capture an image on the screen and convert it to a 
color icon resource. 


Public Domain Color Icon Editors 

There are two different color icon editors available in Public 
Domain. The very first editor released was the application 
‘CIcon Edit’ by Ben Haller of AppleSauce Designs. “Сісоп Edit’ 
allows the users to edit color icons of 32 by 32 pixels size that 
have up to 16 separate colors. The editor can import a 'cicn' 
resource, a ‘ICON’ resource or a “ІСМЯ” resource. This feature 
makes the tool exceptionally good at coloring existing icon art 
work. “Сісоп Edit’ itself is the easiest to use, with a good 
command set to manipulate the image (move, roll, flip, rotate). 
This tool has been around the longest (latest version Г уе seen is 
1.1) and is virtually bug proof. Unfortunately, the application is 
lacking in certain areas. This editor is unable to edit a color icon 
that is any other size than 32 by 32 pixels and 16 colors. There 
is no method of adjusting any other settings of the resource. 
“Сісоп Edit’ does not have a palette of tools (ala MacPaint); the 
user draws the image a pixel at a time. Also, the load command 
does not give a list of all the ‘cicn’ resources of the target file. 
Thus, the user has to keep track of all ‘cicn’ and their ID numbers 
himself. To be really productive with this tool, the user needs to 
work ResEdit. 

The other PD color icon editor solves this problem by being 
a ResEdit extension. ‘ResWare’ by Frédéric Miserey of None 
Corp in Parisconsists of certain resources that the user copies into 
his ResEdit application (replacing some existing ones). Then the 
user can use ResEdit directly to observe, create and edit ‘cicn’ 
resources. This utility is a more powerful editor then “СІсоп 
Edit’. ‘ResWare’ has a complete tool palette that includes pen, 
eraser, fill bucket, lasso, and other rectangle commands. The 
editor can use single color patterns when drawing. There is no 
practical limit to the size of the color icon, nor the number of 
colors. Also the editor allows the user to change other portions 


528 


Tore Steve and Patricia Sheets 
| ko 
[ma Herdon, VA 

THINK Pascal Volume 5, Number 12 


of the ‘cicn’ resource including horizontal and vertical size, 
component count, component size and pixmap method (Chunky, 
Chunky/Planar or Planar). However the editor is still in beta form 
(latest version I've seen is 1.0b4) and has caused numerous 
crashes. ‘ResWare’ has no import feature, and the editor, while 
more powerful, is not as easy to use for beginners as 'CIcon Edit’. 


Importing Images into Color Icons 

While both editors are useful in creating color icons, they 
both suffer from a common fault. They do not allow easy import 
of an image on the screen into a ‘cicn’ resource. At first, it may 
not seem as if this is a problem. Of course, the editor will only 
be used to create a 'cicn' resource. However, this is not always 
the case. Look at what happened with original Quickdraw and 
the creation of ‘ICON’ and ‘ICN#’ resources. Even though there 
were a few icon editors, many non-technical users created their 
images with the more powerful Paint and Draw programs. Then 
they handed the complete art work to a programmer, expecting 
him to be able to use it directly. The programmer had no way to 
directly transfer an art document into a ‘ICON’ or ‘ICN#’ 
resource. In many cases, the programmer had to reenter the 
image into the icon editor one pixel at a time. To solve this 
problem, many programmers created various Icon-Grapper 
types of utilities. These utilities, usually Desk Accessories or 
FKEYs, allowed the programmer to capture any portion of the 
screen and convert it into an icon resource. Since it captured an 
image on the screen and did not need to directly convert any type 
of document, these utilities would work with any Paint or Draw 
application. 

A user who wanted to convert a Pixel Paint or MacDraw // 
image into a ‘cicn’ resource would have the identical problem. 
The problem is further complicated, since the user would have to 
worry not only about the 32 by 32 pixel image, but would have 
to import a color list, a mask and a black and white icon. I had 
this problem. The graphic designer of my latest project presented 
the technical team with a group of Pixel Paint files, each one 
having a dozen or so images on it. It would have taken hours of 
Work to reenter the images using one of the color icon editors. 
That estimate was assuming that the artwork was the finished 
product, and not going to be revised. This started looking like a 
potential nightmare. 


cicnCapture 
The solution to this problem is being provided as the sample 
source code. ‘cicnCapture’ is an FKEY utility that can capture 
a 32 by 32 pixel image of the screen, containing up to 256 
different colors, and create a ‘cicn’ resource that contains this 
image. The code uses the Quickdraw call, GetCPixel, to deter- 
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mine the color of each pixel in the image. Since the code uses this 
call instead of reading the screen PixMap directly, it will work on 
any depth or type of screen or monitor as long as Color Quick- 
draw is installed. Once the image has been captured, the 
information is saved out to a specified resource file. 

Using this utility on our software project, it took a few 
minutes to import all of the color images into ‘cicn’ resource. 
“Сісоп Edit’ and ‘ResEdit’ were used afterward, but mainly to 
make sure the images had the correct ID number, and that they 
were centered on the 32 by 32 pixel icon. 


Next Column 
Anyone remember the game, ‘Daleks’? This application 
was one of the first, and best, Public Domain games around. Next 
issue’s sample code will be ‘Color Daleks’. The program will 
show how to directly draw and manipulate color icons. Various 
color drawing modes will be explained, as well as some anima- 
tion speed up tricks. 


( cicnCapture- Color Icon Capture FKEY ) 

( by Steve Sheets for MacTutor 9/3/89 } 

( FKEY is normal saved to resource type ‘FKEY’, ID = 7 ) 

( This FKEY captures a 32 by 32 Pixel section of the screen 
and converts it into a 'cicn^ resource (Color Icon ) 

( template). When the user activates the Function Key and 
click somewhere on the screen, that portion of the ) 

( Screen is recorded (colors and pixels) and a cicn handle is 
created. Remember a cicn handle is different than ) 

( an actual Color Icon handle. The cicn handle/resoure is a 
template for a Color Icon. The Color Quickdraw ) 

( command, GetCIcon, uses the cicn resource to determine how 
to make a Color Icon. 

( FKEY is written in Think’s Lightspeed Pascal 2.0. ) 


unit cicnCapture; 
interface 


uses 
Quickdraw, ToolIntf; 


( FKEY (function keu) code resources must have be an unit with 
: single externally reference procedure called ) 
'Main'.) 


procedure Main; 
inplementation 
procedure Main; 


( The 'cicn^ resource consists of three variable length parts. 
The first part contains the Pixmap info, the Black ) 

( & White Icon and the Mask. The second part contains the 
Color Lookup table Cie. list of colors used in the ) 

( cicn). The size of this part is dependent on the number of 
different colors in the cicn. The last part of the ) 

( resource is the pixel data. The size of this is dependent 
on the number of different colors in the cicn. If ) 

( there are 2 to 16 colors, the pixel info can be stored in a 
4 bit pixel maip, if the number of colors is 17 to ) 

( 256, then the info must be stored in a 8 bit pixel map. 
Given the fact this FKEY only captures 32 by 32 cicn, ) 

( the size of the first part is fixed, while the size of the 
third part is one of two possible fixed sizes. ) 


type 
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IconData = packed arrau[0..31] of LongInt; 
( First part of cicn resource for a 32 by 32 pixel cicn.) 


cicnData = record 
baseAddr: LongInt; 
rowbytes: INTEGER; 
bounds: Rect; 
pmVersion: INTEGER; 
раскТуре: INTEGER; 
packSize: LongInt; 
hRes: LongInt; 
vRes: LongInt; 
pixelType: INTEGER; 
pixelSize: INTEGER; 
cmpCount: INTEGER; 
cmpSize: INTEGER; 
planeBytes: LongInt; 
pnTable: LongInt; 
pmReserved: LongInt; 


MaskBaseAddr: LongInt; 
MaskRowBytes: INTEGER; 
MaskBounds: Rect; 


BMapBaseAddr: LongInt; 
BMapRowBytes: INTEGER; 
BMapBounds: Rect; 


IconData: LongInt; 
theMask: IconData; 
theBMap: IconData; 
ctSeed: LongInt; 
ctFlags: INTEGER; 
ctSize: INTEGER; 


end; 
cicnPtr = “cicnData; 


( 2nd part (CLUT) of cicn resource for 32 by 32 pixel cicn. 


CTableData = packed arrau[0..255] of ColorSpec; 
CTablePtr = “CTableData; 


{ 3rd part of cicn resource for 8 bit, 32 by 32 pixel cicn. 


pixel8Data = packed array[0..31, 0..311 of 0. .255; 
pixel8Ptr = ^pixel8Data; 


( 3rd part of cicn resource for 4 bit, 32 by 32 pixel cicn. ) 


pixel4Data = packed array(2..31, 0..151 of 0..255; 
pixel4Ptr = ^pixel4Data; 


var 
thePos: Point; 
thePixel8: pixel8Deta; 
theNumColors: INTEGER; 
theIcon: IconData; 
theColorList: packed array[@..255] of RGBColor; 
theCICN: Handle; 


( Tell us if Color Quickdraw is installed on machine. } 


function IsColorQuickdraw: BOOLEAN; 
const 
ROM85Loc = $28E; 
TwoHighMask = $C000; 
type 
WordPtr = “INTEGER; 
var 
Wd: WordPtr; 
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egin 
Wd := POINTER(ROM85Loc); 
IsColorQuickdraw := (BitAndCWd^, TwoHighMask) = Ø); 
end; 


( Sets cursor to show an upper left portion of a square.) 


procedure Ini tSquare; 
var 
count: INTEGER; 
Square: Cursor; 


begin 
with Square do 
begin 
data(@] := $FFFF; 
mask[0] := 0; 
for count := 1 to 15 do 
begin 
data[count] := $8000; 
mask [count] := 0; 
end; 
hotSpot.v := 0; 
hotspot.h := 0; 


end; 
SetCursor (Square); 
end; 


( Wait until the user presses the mouse, making sure the mouse 
was not pressed to begin with. Then stores ) 
( the postion of the mouse and flushes the mouse events. ) 


procedure GetPos; 
begin 
while button do 
while not button do 


GetMouse( thePos); 
FlushEvents(mDownMask + mUpMask, 0); 
end; 


( Given the position of the mouse, captures a 32 by 32 array 
of pixels and a list of the colors. The} 

( pixel information is not stored as RGB values, but as a 
number (zero count) that represents that) 

( RGB value in the Color List Cie. value of 2 equals third 
color in list). Thus every time a pixel on } 

( the screen is looked at with the GetCPixel command, that RGB 
value is looked for in the Color List.) 

( If the color is found, that number is stored in the 2 
dimensional pixel array. If the pixel uses a } 

( new RGB color (not found in the list), that color is added 
to the list. The number that represents) 

( that new color is stored in the pixel array. 
the end, the program knows exactly what } 

( colors are used. The code does not care about the depth of 
the screen (1, 2, 4, 8, 16 or 24 bits } 

( per pixels). However this cicn resource uses the Chunky 
model, thus only 256 colors can be used } 

( Cfairly safe limit). The list will always contain black and 
white as the first two colors in the list.) 

( This procedure also creates a black and white 32 by 32 bit 
icon for the mask and the Black and ) 

( White icon portion of the cicn. Any color other than white 
indicates a black bit. 


This way, at 


procedure GetPixels; 
var 
h, v, theNum, count: INTEGER; 
theColor: RGBColor; 
begin 
theNumColors := 1; 
with theColorList(0] do 
begin 
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red := $FFFF; 
green := $FFFF; 
blue := $FFFF; 
end; 
with theColorList(1] do 
begin 
red := 0; 
green := 0; 
blue := 0; 


thelcon[V] := 0; 
for h := 0 to 31 do 


begin 
GetCPixel(thePos.h + h, thePos.v + v, th- 


eColor); 
theNum := -1; 
for count := 0 to theNumColors do 
T 1f (theColor.red = theColorList[count].red) 
en 


if CtheColor.green = 
theColorList[{count].green) then 
1f CtheColor.blue = 
theColorList(count].blue) then 
theNum := count; 
1f CtheNum = -1) and CtheNumColors < 255) then 
begin 
theNumColors := theNumColors + 1; 
theNum := theNumColors; 
theColorList[theNum] := theColor; 
end; 
thePixel8[v, h] := CtheNum mod 256); 
if (theColor.red o -1) or CtheColor.green © 
-1) or CtheColor.blue o -1) then 
BitSetCétheIcon[V], h); 
end; 
end; 
end; 


( Having pixel infor, allocates memmory for cicn handle.) 


procedure MakeCICN; 
var 
theCICNptr: cicnPtr; 
theCTablePtr: CTablePtr; 
thePixel8Ptr: Pixel8Ptr; 
the4PixelPtr: Pixel4Ptr; 
theRect: Rect; 
count, v, h, theTableSize, theImageRowBytes, theB- 
itsPixel, thePixelDeteSize: INTEGER; 
begin 
SetRect(theRect, 0, 0, 32, 32); 


( If number of colors is more then 16, then use 8 bit pixel 

map, else use 4 bit pixelmep (Rowbytes of pixmap is ) 

( diffent, bit depth is different, size of pixel data is 

со Notice that Rowbutes must have the high bit ) 
set. 


if (theNumColors > 16) then 
begin 
theBitsPixel := 8; 


theImageRowBytes := $8020; 
thePixelDetaSize :- SizeOf(pixel8Data); 

end 

else 

begin 
theBitsPixel := 4; 
theImageRowBytes := $8010; 
thePixelDataSize := SizeOf(pixel8Data) div 2; 


end; 
theTableSize := (theNumColors + 1) * SizeOf(ColorSpec); 
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( Allocate size of handle (dependent on number of colors & 4 
or 8 bit pixelmap. ) 


theCICN := NewHandle(SizeOf(cicnData) + theTableSize + 
thePixe1DataSize); 

HLock( theCICN); 

theCICNptr := POINTERCtheCICN^); 


( Stuff first part of cicn handle. ) 


with theCICNptr^ do 
begin 

beseAddr := 0; 
rowbytes := thelmageRowButes; 
bounds := theRect; 
pmVersion := 0; 
packType := 0; 
packSize := 8; 
hRes := %00480000: 
vRes := %00480000: 


pixelType := 0; 
pixelSize := theBitsPixel; 
cmpCount := 1; 

cmpSize := theBítsPixel; 
planeButes := 0; 

pnTeble := 0; 

pmReserved := 0; 
MaskBaseAddr := 0; 
MeskRowBytes := 4; 
MaskBounds := theRect; 
BMapBaseAddr := 0; 
BMapRowBytes := 4; 
BMapBounds := theRect; 


IconData := 0; 

theMesk := thelcon; 

theBMap := thelcon; 

ctSeed := 0; 

ctFlags := 0; 

ctSize := theNumColors; 

end; 

( Stuff second part, the Color Look Up table (color list).} 
theCTeblePtr := POINTERCORD4CtheCICNptr) + SizeOf (CICNData)); 


for count := 0 to theNumColors do 
with theCTablePtr*{count) do 


begin 

value := count; 

rgb := theColorList([count]; 
end; 


( Stuff the third part of the cicn handle, the actual pixmap 
data. If an 8 bit pixmap is used, the format of ) 

( the data is identical to the array used to store the pixel 
information so the data is simply moved into the ) 

( handle. If the pixmap is a 4 bit one, the pixel info is 
moved into another array that has the format of a 4 ) 

( bit pixmap data, then that data moved into the handle. ) 


1f CtheNumColors > 15) then 
beg! 


egin 
heP ixel8Ptr := POINTERCORD4CtheCTablePtr) + 
theTableSize); 
theP ixe18Ptr^ 
end 
else 
begin 


:= thePixel8; 
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the4PixelPtr := POINTERCORD4(theCTablePtr) + 
theTableSize); 
for v := 0 to 31 do 


for h := 8 to 15 do 
the4PixelPtr^[v, h] 
х 16) + thePixelB[v, Ch * 2) + 11) mod 256; 
end; 


HUnLock( theCICN); 
end; 


( Given a cicn handle, store it into a resource file (new or 
existing one) as a ‘cicn’ resource. ) 


procedure SaveCICN; 
ver 
theWhere: Point; 
theRef, theVol: INTEGER; 
theE: OSErr; 
theReply: SFReply; 
begin 
theWhere.h := 40; 
theWhere.v := 40; 
SFPutFileCtheWhere, “Save Color Icon to File:’, 'cicn 
File’, nil, theReply); 
1f theReply.good then 


theE := GetVol(nil, theVol); 
theE := SetVol(nil, theReply.vRefNum); 
theRef := OpenResFileCtheReply.fName); 
1f theRef = -1 then 
begin 
CreateResF i leCtheReply. fname); 
Hai ‚= OpenResFileCtheReply.fneme); 
eng; 


1f theRef <> -1 then 


egin 
AddResource(theCICN, ‘cicn’, UniqueIDC'cicn?), “° 
Wr iteResource(theCICN); 
Re leaseResource( theCICN); 
theCICN := nil; 


CloseResF i leCtheRef ); 
end; 
theE := SetVol(nil, theVol); 


end; 

if theCICN <> nil then 

begin 
DisposHendleCtheCICN); 
SysBeep( 1); 

end; 

end; 


( Main Procedure. If there is Color Quickdraw, init the 
cursor to a square, get the position of the mouse when the } 
( user clicks, the pixels at that position, convert pixels 
into a cicn handle, save the cicn handle to a resource and ) 
( finally reset the cursor back to an arrow. If there is not 
Color Quickdraw on the machine, complain! } 
begin 
1f IsColorQuickdraw then 
begin 
Ini tSquare; 
GetPos; 
GetPixels; 
MakeCICN; 
SaveCICN; 
InitCursor; 
end 
else 
SysBeep( 1); 
end; 
end. 


:= (CthePixel8[v, (h * 25) 


); 
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"Looking at system queues" 

The utility that I'm going to describe this month can be used 
to look at various queues of the Macintosh operating system. I 
was always curious to know what's going on in the background 
of my machine while I'm working away; that's how this example 
came to be. At the same time, the program contains another 
example of popup menus (for which the correct trap call has been 
added in Mach2.14), and how to use the userData field in the user 
variable area to display messages in a task window. 

A number of queues are maintained by the Mac operating 
system; the example won't list all of them, but some of the more 
important ones. Queues are linked lists of information blocks. 
Each block contains the address of the next list element in its first 
four bytes, a 16-bit number indicating the queue type in its next 
2 bytes, and variable length information thereafter, as indicated 
below: 


(4 bytes) pointer to next element 


(2 bytes) queue type Z 


0002000022 00 U ae ah a e өгө ө oT o e е a o 


КТА e 
Миииниим инни лл tale te tet 


M тан етот тете Уеа 


небе о 9 0.0 9 0 0 0 0 9 a s 0 0 0 0 nese o s о оби 


Fig.1: general structure of a Macintosh queue 


The first element of a queue is called the queue header and 
the last one the queue tail. The queue tail has a link address of 
zero, meaning no more elements will follow. One can access the 
elements of a queue through a pointer to its header which is 
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usually kept in a low memory global variable. For some of the 
queues the tail’s location is kept in another global variable for 
faster access. 

The low memory addresses of the queues that our utility will 
display - vertical blanking queue, volume control block queue, 
drive queue, file system queue, event queue, deferred task queue 
and time manager queue - are defined at the beginning of the 
listing. (Since the address of the TM queue is not given in IM, I 
dug it out of a disassembly of the _InsTime trap.) 


Structure of the program 

We'll set up a Mach 2 terminal task that contains the usual 
Apple, File and Edit menus (for desk accessories). The task 
window will contain a bar display for each queue which gives a 
visual indication of the size of the queue. The display bars are 
‘Click-sensitive’; when the mouse is clicked on one of them, a 
popup menu is displayed which shows the name of the queue. 
When this name is selected, a second window will be opened with 
information about the queue elements. That second window will 
disappear on a mouse click. 


Inter-task communication in Mach2 

I was happily hacking away on the example, got the rec- 
tangles drawn in theright places, the popup menus setup (note the 
slight difference in the interface that's used here - built-in - from 
my code in MT V4#4), when I got a row of bad bombs trying to 
write text into a second window from the queue-monitoring task. 
Just ADDing a new window, then doing a. SetPort and using the 
Mach2 text I/O routines wouldn't work at all. When it finally 
dawned on me... what was I actually doing? The main task 
detects a mouse down in the content region of its window and 
calls the content handler (see listing) to find out which rectangle 
it has been clicked in, which menu to display, and to output the 
text in the second window. Now that is a totally trivial piece of 
code іп a single task program like one would write in C or Pascal 
most of the time. In Mach2, things are different. 

The mouse down event is not detected by the task that is 
supposed to handle it, but by the (in)famous I-O task, present in 
any Mach2 application. That task calls WaitNextEvent, detects 
which window the mouse was clicked in, and calls the event 
handler of the task that owns the window. So while we're 
executing the event handler, we're actually in the context of the 
I-Otask! The standard Mach2 console output would be sent to the 
window associated with the I-O task. Unfortunately, there is no 
such window - therefore bomb. 

The bottom line is that you can't use the Forth text I-O 
routines from event handlers that are called through the I-O task. 
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You have to rely on the means that Mach2 provides to do inter- 
task communication and make a terminal task do the text output. 


Mach2 text output from event handlers 

How is this achieved? The User area of a Mach2 task 
contains two locations, UserData and UserVector. When a non- 
zero value is stored in UserData, the routine pointed to by 
UserVector will be executed. So all we need to do is define a user 
vector handling routine, and have the content handler of the task 
store some message in UserData. 

The content handler of our main window simply stores the 
menu ID of the selected popup menu in UserData. The user 
vector handler finds this menu ID (it gets passed on the stack), 
and calls the corresponding queue display routine. 

The queue display routines use a second window, qInfo. In 
order to have the output appear in that window and not on top of 
our bar display, we have to change the task window pointer 
momentarily; this is done by storing the g/nfo window pointer in 
the user variable taskWindowPointer, doing the output and later 
restoring the original pointer. 


Queues displayed 

The utility displays seven queues (and you can easily add 
more): vertical blanking, volume control block, drive, event, file 
system, deferred task, and time manager queues, in that order. 
The display bars are not labeled, but the popup menu will show 
you the name of the queue when you click on a bar. 

When a popup menu has been selected, a queue list is 
displayed in a second window. The first two columns are the 
element number and queue type for each list element. The 
remaining columns vary according to the queue displayed. For 
the VBL queue, the VBL procedure pointer, the tick count and the 
‘phase’ are listed. The VCB queue gives the name of each 
mounted volume, its drive number, driver and volume reference 
numbers, total number of allocation blocks, allocation block size 
and free blocks. The drive queue will give the drive number, 
driver reference number, file system ID, total number of blocks, 
and the status of the drive (locked disk, disk inserted, single or 
double sided for floppies). The status information is kept in the 
four bytes preceding the queue element (see IM II-128). 

The event queue listing contains the what, message, when, 
where, and modifiers fields of the event. However, I’m sorry to 
say that in this case the listing window is next to useless, because 
the list is always empty when it is displayed. I'll let you think of 
a reason why. The bar display sometimes shows queued events, 
when the display window is brought to the front from a partially 
covered position (its activate and update events). 

Since I never found any pending asynchronous file system 
requests, I could not test the display for the FS queue, so that 
display routine is empty, just like the deferred task display. The 
time manager queue list shows the procedure pointer and count 
field for each time manager task. 

In my system (МасП, 80MB hard disk, 5 MB memory, 
Appletalk and file server installed) I founda total of 8 VBL tasks, 
2 time manager tasks, 2 mounted volumes (hard disk and Ali- 
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sashare volume), and, interestingly, 5 different drives. I could 
make sense of three drives (SCSI disk, floppy drive and Ali- 
sashare disk), and can guess that a fourth ‘drive’, with the same 
file system ID as the Alisashare volume, might have something 
to do with the server. The fifth entry, with a queue type of 3, file 
system ID of $43C, and driver reference number of zero, doesn't 
make sense to me. If someone has something to say about that 
point I'd be happier. 


Why? 

The crucial question - what is this utility good for? Besides 
satisfying the general curiosity of a system hacker, one important 
thing that I can imagine it would be helpful in is the detection of 
- you guessed it - viruses. At least background routines that install 
VBL or time manager tasks to do their malicious job might be 
spotted a lot easier when the queue display suddenly starts 
changing. 

I did not add information about working directory control 
blocks, but you may do so if you like. The working directory 
queue header pointer is at $372. 


Mach2 news 

Finally, Palo Alto Shipping has published a trap compiler 
that allows you to add new traps to the Mach2 system without 
writing assembly code. The code is freely accessible on the 
Mach2 GEnie roundtable, but for those of you who don't have 
access to GEnie, I' m including it on the source code disk together 
with some trap fixes for version 2.14. Sorry we can't print the 
complete code here because it is too long; also you'll have a lot 
of glue code typed in and debugged before you have finished 
typing the trap compiler in by hand. I'll nevertheless print a short 
extract of the description: 

This utility allows you to define your own trap "glue." Thus 
as new system traps become available, you will be able to define 
their high-level interface symbolically (without using assembly 
language). It will also allow you to define a substitute syntax to 
the CALL interface, in case you need to modify (fix?) one of the 
existing traps. Note that in the latter case, you do not actually 
change the existing CALL, you simply define a new syntax 
which can be used in place of the CALL sequence. 

One might wonder whether it makes good sense to include 
a2K utility inan application when all you need is a few trap calls 
(but, see my comments below). However, for casual use you 
might consider putting this code in your workspace, along with 
your commonly used constants, mach words, and other compiler 
utilities (that way they will always be available during your 
"experimental" sessions). If you are working on a serious 
application, I would suggest the following approach. Place all 
variables, mach words, and compiler utilities (such as this trap 
compiler) in a separate segment and when you finish your 
application use ResEdit to remove that very same segment from 
your finished application. 

This will work because mach words, variables, and compiler 
utilities (such as this trap compiler) do NOT need to be in memory 
during the execution of the code which they produce. Generally 


@ The Best of MacTutor, Vol. 5 


speaking, any word which only produces in-line code, most уйны е о, ыы w, ДЫ w, 4i и, 2 w, 
А ; . . . create rec W, W, W, и, 
immediate words, or any child word which does not reference its create rect5 20 w, 80 w, 9 и BB w 
parent at run-time can safely be removed from a finished appli- | create rect6 20 w, 95 w, 90 w, 103 w, 
cation. If you are really concerned about making the smallest | create rect? 20 w, 110 w, 90 w, 118 W, 
possible applications, then this is a technique which you should 
alwaysuse (as a finalstep, when you are completely finished with 
your program). If it seems risky to remove a segment from a | NEW.MBAR queueBar 
finished application, Just remember that there is NO WAY YOU | NEW.MENU AppleMenu 
can run code in another segment if that segment has NO Jump- | APPLESTRING AppleMenu TITLE 
table entries (i.e. if you can’t get to the code, why include it in | ? Raise о. € M 
your application?) out Queues ...; ppleMenu 

Mach words, variables, and (most) compiler wordsdon'tuse | NEW. MENU FileMenu 
or create jump-table entries. This same principle is why you | ^" File” FileMenu TITLE 

: 9 FileID FileMenu BOUNDS 

never have to mark mach words or variables as GLOBAL (there * Quit” FileMenu ITEMS 
is one exception, if you write a CODE word which explicitly 
states “JSR «mach word»" or “LEA «mach word»" then the 222 
defined instance of that <mach word> mustbein memory at run- 0 EDIT ID ER ams. BOUNDS 
time. Thus if «mach word» exists in another segment, it will need " (Undo/Z;(-; (Cut/K; (Copy/C; (Paste/V; CClear^ EditMenu ITEMS 
10 be marked GLOBAL (however, it's always ok to say LEA ЕЕ 
«variable» ог MOVE.L «variable», thus variables “never” need | `! vb 1” ШЕТТЕ 
to be marked as GLOBAL). -1 150 vblmenu BOUNDS 

Waymen @ PASC ” VBL Tasks; (-^ vblmenu ITEMS 


ae . NEW.MENU vcbmenu 
Thanks for that utility and the comments on segmentation. “ усь“ vcbmenu TITLE 


CREATE APPLESTRING 01 С, $14 С, 


Till next month. -1 151 vcbmenu BOUNDS 
“ Vol contr] blks;(-^ vcbmenu ITEMS 
Listing 1: System queue display NEW.MENU drvmenu 
TT I * drv^ drvmenu TITLE 
\ mini task to display system queues -] 152 drvmenu BOUNDS 


\ © 1988 J. Langowski / MacTutor “ Drives;C-^ drvmenu ITEMS 


only forth also assembler also mac NEW.MENU evtmenu 


" еуі” evtmenu TITLE 
-] 153 evtmenu BOUNDS 
* Events [???]; (-" evtmenu ITEMS 


$160 constant vblqhdr 
$356 constant vcbqhdr 
$308 constant drvqhdr 


$148 constant evtqhdr NEW.MENU f 
$360 constant fsqhdr ” fs” 2. 
9092 constant dtqhdr -1 154 fsmenu BOUNDS 


$b30 constant timevars 


$11c constant utablebase * File System;(-” fsmenu ITEMS 


NEW.MENU dtmenu 


12 user taskwindowpointer " dt" dtmenu TITLE 

92 user (type) -1 155 dtmenu BOUNDS 

108 user taskmenubar * Def Tasks;(-^ dtmenu ITEMS 
144 user uservector 

148 user userdata NEW.MENU tmmenu 

152 user content-hook ” tm^ tmmenu TITLE 

164 user goaway-hook -] 156 tmmenu BOUNDS 


168 user update-hook 


“ Time manager;(-^ tmmenu ITEMS 
172 user activate-hook : 


NEW.WINDOW SysQueue 

“ System Queues” SysQueue TITLE 

250 50 350 250 SysQueue BOUNDS 

Rounded Visible CloseBox GrowBox SusQueue ITEMS 


2 CONSTANT Message 
10 CONSTANT Where 
14 CONSTANT Modifiers 
1 CONSTANT ActivateMask 
| NEW.WINDOW qInfo 
300 constant appleid * Queue Info” qInfo TITLE 
301 constant fileid 90 58 250 500 qInfo BOUNDS 
302 constant editid NoGrow Invisible NoCloseBox NoGrowBox qInfo ITEMS 
152 CONSTANT WrefCon 500 2000 terminal queues 
create recti 20 w, 20 w, 90 w, 28 w, CODE unpack 
create rect2 20 w, 35 w, 90 w, 43 ú, MOVE.L (A62,D0 
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CLR.L 01 
MOVE.W 00,01 
CLR.W DO 
SWAP .W 00 
MOVE.L D0,(A6) 
MOVE.L D1,-CA6) 
RTS 

END-CODE MACH 


‚ beep Сп) 
@ do 1 call susbeep loop 


: wait ( 8ticks | time - ) 
call tickcount "ticks + -> time 
begin pause 
call tickcount time > 
until 


: popup.select ( menu pt | point – menuID item? } 
pt — point 
^ point call localtoglobal 
menu @ point unpack 1 
call popupmenuselect 
unpack 


: do.content ( | pt - ) 
CALL FrontWindow CALL SetPort 
qInfo call HideWindow 


RUN-CONTENT 
EVENT-RECORD Where + ё -> pt 
* pt CALL GlobalToLocal 


0 
pt rect! CALL PtInRect 
IF drop vblmenu THEN 
pt rect2 CALL PtInRect 
IF drop vcbmenu THEN 
pt rect3 CALL PtInRect 
IF drop drvmenu THEN 
pt rect4 CALL PtInRect 
IF drop evtmenu THEN 
pt гесіб CALL PtInRect 
IF drop fsmenu THEN 
pt rect6 CALL PtInRect 
IF drop dtmenu THEN 
pt rect? CALL PtInRect 
IF drop tmmenu THEN 


?dup IF С rectangle was selected) 
pt popup.select 


IFC popup selection was made ) 
C menuID ) userData tesk-? queues ! 
THEN 

THEN 


: drew.rects 


rect3 call 
rect4 call 
rect5 call 
rect6 call 
rect? call 


eraserect 
eraserect 
eraserect 
eraserect 
eraserect 


rect! call 
rect2 call 
rect3 call 
rect4 call 
rect5 call 
rect6 call 
rect? call 


: clr.rects 
rect! call 
rect2 call 
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fremerect 
framerect 
framerect 
framerect 
framerect 
fremerect 
framerect 


eraserect 
eraserect 


: blackBar ( rect pixels | locBR locTL ) 
rect ^ locTL 8 cmove 
^ locBR w@ ( bottom ) pixels - 
^ locTL w! 
~ locTL call paintrect 


: felems ( qhdr | elems - *.of .queue.elements ) 

0 -> elems 
2 +) qhdr 
begin 

qhdr @ ?dup while 

-) qhdr 

1 +> elems 
repeat 
elems 


: display.queues ( | – } 

clr.rects 

draw.rects 

recti vblqhdr 5elems 4% blackBer 

rect2 vcbqhdr *elems 4% blackBar 

rect3 drvqhdr *elems 4* blackBar 

rect4 evtqhdr #elems 4* blackBar 

rect5 fsqhdr #elems 4% blackBar 

rect6 dtqhdr #elems 4% blackBar 

rect7 timevars 6 8 + Yelems 4* blackBar 


: dsp.vb1 ( | qelemPtr n - ) 
cis 
qinfo ^ Vertical Blanking Tasks" 
call SetWTitle 


i Гг 
." task® qtupe ProcPtr Count Phase" cr 
es ^ cr 
vblqhdr 2+ -> qelemptr 
1 -› п 
begin 

qelemptr @ ?dup while 

-) qelemptr 

n 3 .r 3 spaces 

hex 


qelemptr 4 + w@ 5 .r space 
qelemptr 6 + @ 8 .r space 
qelemptr 10 + «6 5 .r space 
qelemptr 12 + we 5 r cr 
decimal 
l+ n 

repeat 


: dsp.vcb ( | qelemPtr n - ) 
cls 
qinfo “ Volume Control Blocks” 
call SetWTitle 


жы мл F 
% cr 
‚усб qtype Volume name Drive dRef? vRef# "blks blksz 
free" cr 


ә 


SS СГ 
vcbqhdr 2+ -> qelemptr 
1n 
begin 


qelemptr 8 ?dup while 
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-) qelemptr 

n 3 .r 3 spaces 

hex 

qelemptr 4 + же 5 .r space 

qelemptr 44 + count dup rot swap tupe 
27 swap - spaces 


qelemptr 72 + w@ 5 .r space 
qelemptr 74 + w8 5 ‚г space 
qelemptr 78 + w8 5 .r space 
qelemptr 26 * w8 5 .r space 
qelemptr 28 + 6 5 .r space 
qelemptr 42 + ме 4 r cr 
decimal 

1+ n 


repeat 


: dsp.drv ( | qelemPtr n - ) 
cis 
qinfo ” Drives" 
call SetWTitle 
uu —————— RN Ж cr 
drv# qtype Drive dRef# FSID 8blks 1 dd ss" cr 
Lb—  — “ — PP no .Ü- —!— — H cr 
drvqhdr 2* -› qelemptr 
1-› п 
begin 
qelemptr @ ?dup while 
-) gelemptr 
n 3 .r 3 spaces 
hex 
qelemptr 4 + wê 5 .r space 
qelemptr 6 * w8 5 .r space 
qelemptr 8 * w8 5 .r space 
qelemptr 10 + w8 4 .r space 
qelemptr 12 * we 
qelemptr 4 + w@ 1 = IF 
qelemptr 14 + w@ 65536 * + 
THEN 
8 .r space 
qelemptr 4- c@ $80 AND 
IF ascii u emit ELSE ascii n emit THEN space 
qelemptr 3- c@ 2 .r 2 spaces 
qelemptr 1- ce $80 AND 
IF ascii n emit ELSE ascii y emit THEN cr 
111 
1 +) 
ма" 


: dsp.evt ( | qelemPtr n - } 
cls 
qinfo “ Queued Events” 

сап SetWTitle 
' —————————————————————— — 9 
i drv® qtupe What Message When Where Mods" 
d ——————— '"d—" 
evtqhdr 2+ -> qelemptr 


1-›п 

begin 
qelemptr @ ?dup while 
-) qelemptr 
n 3 .r 3 spaces 
hex 
qelemptr 4 + w@ 5 .r space 
qelemptr 6 + w8 5 .r space 
qelemptr 8 + 6 8 г space 
qelemptr 12 + @ 8 .r space 
qelemptr 16 + @ 8 .r space 
qelemptr 20 * w8 4 .r cr 
decimal 
l+ п 


repeat 
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cr 
cr 
cr 


: dsp.fs 


cis 
qinfo * File System Requests" 
call SetWTitle 


: dsp.dt 


cls 
qinfo ” Deferred Tasks” 
call SetWTitle 


: dsp.tm ( | gelemPtr n - ) 


cls 
qinfo * Time manager” 
call SetWTitle 
—M———M—MÀ———— 2. 4 cr 
." task? qtype ProcPtr Count” cr 
ғ ey | cr 
timeVars e 10 + -> gelemptr 
1> n 
begin 
qelemptr 8 ?dup while 
-> gelemptr 
n 3 .r 3 spaces 
hex 
qelemptr 4 * w8 5 .r space 
qelemptr 6 * 6 8 .r space 
qelemptr 10 + w@ 5 r cr 
decima] 
l+ n 


repeat 


: do.user 


qInfo dup call showwindow call selectwindow 
qlnfo taskwindowpointer ! 

( menuID ) CASE 

150 OF dsp.vb! ENDOF 

151 OF dsp.vcb ENDOF 

152 OF dsp.drv ENDOF 

153 OF dsp.evt ENDOF 

154 OF dsp.fs ENDOF 

155 OF dsp.dt ENDOF 

156 OF dsp.tm ENDOF 
ENDCASE 

SysQueue taskwindowpointer ! 


: do.update ( | pt - ) 


sysQueue call setport 
draw.rects 
run-update 


: do.activate 


event-record modifiers + wé 
1 AND \ Activate event? 
IF 

call DrawMenuBar 
ELSE 


THEN 


: do.close 
bye 


: INIT-MBAR 


queueBar ADD 

queueBar APPLEMENU ADD 

APPLEMENU 8 ascii DRVR CALL ADDRESMENU 
queueBar FileMenu ADD 
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queueBar EditMenu ADD 
queueBar vblmenu add 


queueBar vcbmenu add : go.queue ( | mb - ) 

queueBar drvmenu add activate 

queueBar evtmenu add 

queueBar fsmenu add (41 do.content content-hook ! 
queueBar dtmenu add (^) do.update update-hook ! 
queueBar tmmenu add [^] mbar-handler menu-vector ! 


(^] do.activate activate-hook ! 
(71 do.close goaway-hook ! 


. DO-APPLE ( itemtt | ( 32 lallot 1 deNeme - ) [^] do.user uservector ! 
item? 1 = 
IF3 beep begin 
pause 
ELSE AppleMenu @ sysQueue call setport 
item! ^ DAName CALL GetItem display.queues 
* DAName CALL OpenDeskAcc DROP 60 wait 
THEN egain 
: do-file : start 
drop bye SysQueue add 
; QInfo add 
SusQueue queues build 
: MBAR-HANDLER С item menuID - ) SusQueue WRefCon + @ 
CASE QInfo WRefCon + ! 
APPLEID OF DO-APPLE ENDOF SusQueue dup call selectwindow call setport 
FILEID OF DO-FILE ENDOF init-mbar 
drop queueBar queues mbar? task 
ENDCASE queues go.queue FF 
CALL HILITEMENU (94. 
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Forth Forum 


Record Definitions 


“Record definitions in Mach2” 

Record structures and arrays are not part of standard Forth 
implementations. More than two years ago, in V2#7, I had given 
an example how to implement records. Mach2 has evolved since 
then, and so have ways of implementing new data structures, as 
you can see in the Object Forth project by Wayne Joerding that 
we recently discussed. For those of you who do not want a full 
object-oriented system, but still ways of defining data structures 
in an easy way, I have found two examples on the GEnie bulletin 
boards. Those examples show two fundamentally different 
approaches to deal with record definitions. 


‘Local’ field names - method 1 
The problem in setting up the Forth compiler to deal with 
record definition in a proper way is somewhat similar to imple- 
menting an object-oriented programming system. That is, just 
like a message is local to an object, and the same message may 
cause different effects on different objects, a field name should 
be local to a record. In the Pascal record definitions 


rec! = record 
x: real; 
i: integer; 
y: real; 


rec2 = record 

: real; 

: Integer; 
: real; 


x <. 


end; 


the field x would create a different offset into a record of type 
rec2 than for a rec! type; and recl і, rec2.j would be valid while 
recl j,rec2.i would not. So if we define a field name as some kind 
of Forth word, this word should be in some ‘local vocabulary’ 
that belongs to the record definition and is only visible while the 
field reference is resolved. 

The other requirement is that we should be able to pass a 
record as a parameter to a routine, so that given the pointer to a 
record on the stack, a Forth definition would know how to resolve 
the field reference. In a strongly typed language like Pascal this 
is easy; field references into record formal parameters can be 
resolved at compile time because the procedure arguments are of 
defined type. In Forth, typically the address of a data structure 
would be passed on the stack. However, at compile time there is 
no way we can restrict the type of argument that this address 
might later point to at run time! This problem could only be 
solved by type checking built into the record definition and 
deferring the resolution of the field reference to run time, some 
sort of ‘late binding’. 
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The first method of record definition (Listing 1), written by 
Waymen Askey of Palo Alto Shipping (I added some minor 
modifications, like floating point and array support), creates a 
local dictionary for each record template in the Forth dictionary 
space. When a record template is defined, using the syntax 


template rec1 
‘real x 
‘word i 
‘byte c 
tend 


its field names x, i and c are compiled into the dictionary 
together with relevant information for resolving the references. 
At the end of the template declaration, the dictionary links are 
changed in such a way that the ‘local’ names are skipped when 
the dictionary is searched. Let’s declare a record: 


recl structure myRec 


A field of this record is later accessed by using the structure 
fetch/store words, s@ and s/. 

myRec x s@ will put the value in field x of myrec on the 
floating point stack, and myRec i s( will put the word value of 
field i on the stack. The trick Waymen used was to build some 
intelligence into the fetch/store words. When the record and field 
words, myRec and x for example, are executed or compiled into 
a definition, field type and offset are determined and kept in 
global variables. The s(2 word will check these variables and 
know how to access the field, whether - in immediate execution 
- to doa byte, word or long word fetch, addressing into an array, 
oraten-byte fetch onto the floating point stack for a real number; 
or at compile time create code that will do these things later. 

The drawback of this approach is that field references can 
only be resolved at compile or immediate execution time. If we 
wanted to write a word that operates on a record whose address 
is passed on the stack, we couldn't use the field names that were 
defined in the record template - they are only valid right after a 
record name was executed or compiled. Therefore, a definition 
like 


: getX ( myRec - ) myRec x sé ; 


must fail because myRec is a local variable, not a record 
name. 

An example how to use this method of record declaration 
with various field types is given at the end of the listing. You see 
the drawback: Even though the record fields wavelength, tem- 
perature, and angle are all themselves structures of the same type 
parameter, there is no way to factor out the common code in 
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cr curvel wavelength name s^ count type .” = “ 
curvel wavelength value së f. 
curve! wavelength unit s^ count type 

cr curvel temperature name s^ count type ." =” 
сигуе1 temperature value së f. 
curve! temperature unit s^ count type 

cr curvel angle name s^ count type .” = * 
curvel angle value 56 f. 


curvel angle unit s^ count type 


by using a word that would just print name, value and unit of 
any given parameter. If this problem was resolved, the record 
compiler would almost be perfect. 


‘Global’ field names - method 2 

Listing 2 shows a much simpler approach to structure 
definitions that does not do type checking. I downloaded this 
code from the Forth Roundtable on GEnie, and unfortunately 
have not the slightest idea who the author is. All I could find out 
was that the original code was probably posted on the East Coast 
Forth Board. 

However, since this code solves one of our problems, record 
passing as formal parameters, I'd like to print it here. Its strategy 
is much more like that of the structure words built into MacForth 
Plus. Here, a record template is defined like 


RECORD Rectangle 
Global 
Global 
Global 
Global 

ENd . RECORD 


SHORT: Top 
Short: Left 
Short: Bottom 
SHORT: RIght 


Variable myRect Rectangle 4 - VALLOT ; 


so therecord name, when executed, simply leaves the record 
length on the stack for later ALLOT or VALLOT. The field 
names are words which add the field offset to an existing address 
on the stack, so they can be used in any context. We have to check 
ourselves whether the address is a valid record address and 
whether the field referenced actually exists in that record (if we 
care at all). All field names are global, and therefore must be 
unique; notwo different record declarations can have fields of the 
same name at different offsets. 

This approach is not so different from the very basic one that 
I used in most of my examples, where I simply defined field 
names as constants and added the offset to the record address. 

What the Macintosh Forth world needs is really a combina- 
tion of the two approaches, with type checking at compile time 
and local field names for convenience, anda possibility to resolve 
field references on record addresses at compile time without too 
much overhead. If one knew the type of the record passed on the 
stack ahead of time (which is usually the case), one could 
probably define some “field reference resolution word" which 
computes an offset given a template and a field name. I hope I can 
show you an example in one of my next columns. 

Upcoming: an update to Wayne Joerding's Object Forth, 
and a review of PocketForth, a public domain 16-bit Forth that 
comes as an application and a desk accessory. Stay tuned. 
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Listing 1: Structure definitions with local field names 
N STRUCTURES 2.5 for the Macintosh MACH2 

N Jan 3, 1987 by Waymen Askey 

\ edited, floating point & array addition by 

N J. Langowski @ MacTutor 

\ This MACH2 extension is released for the public good; 

X however, for those planning commercial use of this code, 

\ please notify me so that I might know of its intended use. 
N Waumen Askey @ PASC 

\ also GEnie MACH2 RoundTable. 


only mac also sane also forth definitions 

( VARIABLES used in STRUCTURE 2.5 ) 

decimal 

variable current. template 

variable op. type 

variable Aboffset C holds the A5 offset to a structure ) 


( CODE word utilities used in STRUCTURE 2.5 ) 
code var.link (- а | variable link pointer ) 
lea $F7F8(A5),A0 
move.1 Ай,-(Аб) 
rts 
end-code 


code ab@ ( -a ) 
поуе.1 A5,-CA6) 
rts 

end-code mach 


code get.field С al a2 — аз -1 or Ø | searches templates ) 
( al=template, a2= pad, a3=field pointer, Ø if not found ) 
move.] CA62*,D2 
move.] (А62%,03 
moveq.] 80,01 
moveq. 1 #0,0@ 
@start тоуеа.1 D3,A1 
поуеа.1 02,А0 
move.b (А12%,01 
beq.s ёепа 
move.b (А12,00 
cmpm.b (А12%,(А02% 
dbne 00,61оор 
beq.s @found 
add.1 01,03 
bra.s @start 
movea.] 03,А1 
move.b 1(А12,01 
addq.w 82/01 
btst #0,01 
beq.s @even 
addq.w #1,D1 
add.1 01,03 
moveq.1 #-1,D1 
поуе.1 D3,-(A6) 
@end move.] 01,-САб) 


С link to next field ) 
( if link=8, field not found ) 


@ loop 


( increment field pointer ) 


@found 
( get string count ) 


( test for odd count ) 


@even 


rts 
end-code 
code ›$г (n- | push value onto subroutine stack ) 
тоуе.1 CA6)+,-CA7) 


rts 
end-code mach 


code s» (С -n | pop value from subroutine stack ) 
тоуе.1 CA7)+,-CA6) 
rts 

end-code mach 


code sr@ ( -n | copy value from subroutine stack ) 
move.1 (A72,-(A6) 
rts 

end-code mach 
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( Miscellaneous utilitu words used in STRUCTURE 2.5 ) 
: )even Ca-a' | 
word aligns address, i.e. rounds up to even) 
dup land +; 


20044 С a-a’ | odd aligns address, rounds up to odd ) 
lor ; 


: needed (Сп - | checks for at least n items on stack ) 
depth 1- > abort” Missing needed stack item(s)! “ ; 


( Brute-force machine code words ) 


: Ncode, 
C nl...n - | machine code defining word, stuffs n words ) 
create dup needed dup 2* w, 
9 do w, loop 
does ( - | compiles machine code ) 
dup 2+ swap dup we + 
do i wẹ w, -2 +loop ; 
hex 


( define some machine code "stuff^ words ) 
4]ED 1 ncode, lea_d(a5),a0 
4EBA 1 ncode, jsr_d(PC) 
4EAD 1 ncode, jsr.d(A5) 
( LEA and JSR also need a word of extension for displacement ) 
2D3C 1 ncode, move. 1_#,-CA6) 
С plus а long extension for & ) 
2008 1 ncode, move.1.80,-(86) 
4Е75 1 ncode, rts, 
С The following expect an address to be in Ай ) 
7000 1010 2000 3 ncode, byteé 
1000 3010 2000 З ncode, wordé 
2010 1 ncode, longe 
201E 1080 2 ncode, byte! 
201Е 3080 2 ncode, word! 
209Е 1 ncode, long! 
\ disassemble the following to check how they work. 
\ Exercise for the reader... - JL 
9187 5587 2247 22d8 2248 32d8 6 ncode, realé 
2241 2009 20d9 30d9 5087 5487 6 ncode, real! 
201е е580 2d30 0000 4 ncode, аггау8 
201е е580 219e 0000 4 ncode, array! 
20 1е e388 4281 3230 0000 2001 6 ncode, warrayé 
201е e380 221е 3181 0000 5 ncode, warray! 
decimal 


( Dictionary header, name, and struct link words ) 


: link>name С lfa- “nf | ‘nf points to header length byte) 
4+; 


: name.count 
( “nf — 'nf*1 n | dictionary header name count) 
count 31 and ; 


: link? segment 
( Ifa - ‘sf | “sf is the dictionary segment field address) 
link?name name.count + even ; 


: link» parameter 
С lfa - ‘pf | ‘pf is the parameter field pointer) 
link?segment 2+ ; 


: lin?struct € Ifa - struct.fields ) 
link?segment 4 + ; 


: jsr_d(PC), 
jsr -dCPC) 
link?body here - w, ; 


( lfa - | compiles PC relative JSR) 


: jsr-d(A5), 
С lfa - | compiles A5 relative JSR, i.e. jump table ) 
jsr -dCA52 
link?paremeter мё w, ; 
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: Struct.zero С - lfa | returns Ifa of struct.zero ) 
“ Struct.zero" find drop ; 


: nallot ( n- | allots n bytes in name space ) 
пр +! ; 


: пате, С — parses and compiles text into name space.) 
32 word np ё over cé 1+ dup odd nallot cmove : 


д 


: nc, Сп - | compiles byte into name space ) 
np 8 c! 1 nallot ; 

: nw, (n- | compiles word into name space ) 
n êw! 2 nallot ; 

: n, (n - | compiles long into name space ) 
np @! 4nallot ; 


on 


TEMPLATE, STRUCTURE and field words ) 

: Struct.error ( - ) 

cr pad count type 

."^ ? Error, unknown field or incomplete structure path! ” 
abort ; 


global 
: template ( - here 0 | begins TEMPLATE definition ) 
create here 0 2 allot 
does? ( - template.size ) 
dup wẹ swap 4 - body? link current.template ! ў 
: tend 


( here n - | CDemplateCEND) ends template definition ) 
swap w! бг, ; 


global 
: afield С size op.type - ) 
create w, even w, 


does? ( here Toffset - here new.Toffset ) 
( Toffset means (TDemplateCOFFSET) ) 
2dup 2+ wê + sr 
we np ё ›ѕг 1 nallot name, 
0 nc, C field type-0 ) nc, C op.type ) 
nw, C Toffset ) np @ sre - sr? c! С field link ) 
sr) ; 


( The following op.tupes are reserved and defined below ) 
( 06 byte, 12 word, 18 long, 24 string, 
30 real, 36 struct, 42 array, 48 warray ) 


С size. in.bytes op.type AFIELD named.afield.type ) 
1 06 afield :byte 
2 12 afield :word 
4 18 afield :long 
1030 afield :real 


: :String С here Toffset size - here Toffset*size*1 ) 
З needed 1+ over +  »even swap 
пр 6 25 1 nallot name, 
0 nc, C field type=ð 2 24 nc, С op. type=24) 
nw, C Toffset ) пр ё sre - sr? c! C field link ) ; 


: :err&y (С here Toffset size - here Toffset*size*1 ) 
З needed 4% over + swap пр 69057 1 nallot name, 
0 nc, C field type-0 2 42 nc, С op. type=42) 

nw, С Toffset ) np 8 sre - sr?» c! C field link ) ; 


: iwarray С here Toffset size - here Toffset*size*1 ) 
З needed 2% over + swap пр @>sr 1 nallot name, 
Ø nc, C field type-0 ) 48 nc, С op. type=48) 
nw, € Toffset ) np 8 sre - sr? c! C field link ) ; 


: :struct С here Toffset size — here Toffset*size ) 
З needed over +  »even swap 
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np 6 25 1 nallot name, 


06 nc, C field type-06 ) 36 nc, С op.type=36 ) : pushA5 C - | executes А5 var reference ) 
nw, ( Toffset ) aboffset 8 а5@ +, 
current.template @ struct.zero - n, C template link ) 
np ё sr@ - sr? c! C field link 2 ; : do.bit (C - ) ( I’m lazy, def ine your own. W. Askey ) 
cr .” BIT operations are yet undefined!” abort ; 
: ypad Са - | moves string to pad ) 
pad over сё 1+ стоме ; : do.struct (- ) С Fetch/store doesn’t make sense here. ) 
cr .” STRUCTURE fetch/store operations are undefined! ^ 
' make.var.link ( | name.pointer var.pointer vlink – ) abort ; 
np 6 -> name.pointer уаг.Тіпк @ -> var.pointer 
name pointer var.link ! : do.string ( - ) С If you wish, define your own. ) 
пате pointer var.pointer - -) vlink cr .” STRING fetch/store operations are undefined! “ abort ; 
name.pointer dup 1 and + -? name.pointer 
vlink name.pointer ! : do.byte@ Cf - ) 
name.pointer 4 * np ! ; if compileA5 byte@ else pushA5 сё then ; 
( Decision table for field type decode ) : do.word@ ( f - 2 
: do.afield С ^field.type - true ) if compileAS word@ else pushAd иё then ; 


1+ dup cê op.type ! 1+ we Aboffset +!  -1; 
: do.long@ Cf ~ 2 


: do.bfield € ^field.type - new.template false ) if compileA5 long@ else pushA5 6 then ; 
dup 1% dup cê op.type ! 1+ we A5offset +! 
4*6  struct.zero + Jlink»struct 0; : do.array@ С idx f – ) 


if compileA5 array@ else 4% pushA5 + 6 then ; 
: rts rts, ; immediate 


: do.warray@ € idx f - 2 


( DO.FIELD table entries decode field data ) if compileA5 warray@ else 2* pushA5 + w8 then ; 
( afield’s are simple :BYTE, :WORD, 
‘LONG, :STRING types ) : do.real@ Cf - ) 
С bfield’s are :STRUCT fields 2 if compileA5 real@ else pushA5 (6 then ; 
create do.field С field type table_offset/type ) ( Decision table for fetch ) 
1 do.afield rts С afield 0 2 create op.table@ С op.types аге offsets into this table ) 
do.bfieldrts С bfield 6 ) ] do.bit rts ( op.type = Ü ) 
[ ( end of current table ) do.bute@ rts С.Л e" = O.) 
do.wordé rts Ce © RV 
global do. long@ rts Се *" = 18 etc, etc. ) 
: make.struct С template.link Aboffset - ) do.string rts 
( This is the word which must resolve a structure reference. ) do.realé rts 
ABoffset ! € A5 displacement for the struct ) do.struct rts 
36 op.type ! С set default op.type to struct ) do.array@ rts 
struct.zero + link»struct С template.address - ) do.warrayé rts 
begin [ 
32 word pad 
pad get.field : do.byte! Cf -) 
if C field found ) if compileAS byte! else pushA5 c! then ; 
dup cê do.field + execute 
else C field not found ) : do.word! Cf - ) 
pad find 1 = if compileAS word! else pushA5 w! then ; 
if 
link body execute -1! : do.long! (f - ) 
else if compileA5 long! else pushA5 ! then ; 
struct.error 
then : do.array! (С idx f - ) 
then if compileA5 array! else 4% pushAS + ! then ; 
until ; 
: do.warray! € idx f - 2 
hex if compileA5 warray! else 2* pushA5 + w! then ; 
: Structure 
( n- | creates structure alloting n bytes in variable space ) : do.real! Cf - ) 
| needed create immediate make.vaer.link if compileA5 real! else pushA5 f! then ; 
-4 allot lea_d(a5),a® vp @ w, С variable-like beginning ) 
move.1_%,-CA6) current.template 6 struct.zero - , create op.table! ( decision table for store ) 
move.1_%,-C(A6) ур ё, ] do.bit rts 
« make.struct^ find drop dup link?segment мё 0= do.byte! rts 
if jsr-d(PC), else jsr-d(A5), then do.word! rts 
rts, do. long! rts 
vallot ; do.string rts 
decimal do.real! rts 
do.struct rts 
( STRUCTURE operators ) do.array! rts 
: compileAS С – | compiles A5 reference ) do.warray! rts 
lea.d(a52,aÜ0 adoffset 8 w, ; [ 
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: $^ ( -a | returns pointer to structure field ) 

( ALL field types are allowed. i.e. strings, struct, etc. ) 
State 6 
if compileA5 move.l_a@,-(a6) else pushA5 then 

; immediate 


: sê С - data | Fetch field contents, data type smart) 
state 6 
op.type 6 op.table@ + execute ; immediate 


: S! С data - | Store into field, data type smart) 
state 6 
op.type @ op.table! + execute ; immediate 


: Stype С — op.type | returns the op.type of a field ) 

op.type ё state 6 

if [compile] literal then 
; immediate 
( Examples of structure usage. Data Storage is limited to the 
approximately 32K global area referenced off of register A5 - 
just as for regular MACH2 variables. Structure references have 
8 REQUIRED syntax, it is best NOT to use any non-STRUCTURE 
Forth words when between field names in a structure calling 
sequence. That is, please end each structure reference prior 
to any DUP’s, SWAP's, etc. The structure pointer operator - S^ 
- mày be used at any place in the structure calling sequence. 
57 will return the address of the field or structure itself. 
Structures MUST be terminated with a def ined structure 
operator! The defined operators in this upload are 9^, Se, 
S!, and STYPE. WARNING, if you forget to terminate a struc- 
ture, no structure reference will be compiled and an error 
message MAY NOT be given. Remember also that field names ARE 
CASE SENSITIVE and LOCAL to the structure template. Last 
comment, structures MAY be nested to any level. ) 


fp 


template Point 
‚мога x 
‘word у 

tend 


template Rect 
‚мога top 
‘word left 
:word bottom 
‘word right 
tend ( TEND ends template definition ) 


\ example for FP parameters 
template parameter 
30 :string name 
‘real value 
30 :string unit 
tend 


template measurement 

: long date \ in internal Mac format 
80 :string title 
255 :string descriptor 


parameter ‘struct wavelength 
parameter :struct temperature 
parameter :struct angle 


256 :аггау time 
256 :аггау counts 
tend 


measurement structure curvel 
: testarray 


100 @ do i 4* i curvel time s! loop 
100 0 do i curve! time s@ . cr loop; 
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: .date € DateTime DateForm ) ( | [ 40 lallot ] mydate - ) 
8 shift ^ mydate call IUDateString ^ mudate count type; 


: read. int 
begin 
pad 1% 80 expect span 6 pad c! pad number? not while 
drop cr .^ Illegal number [integer], reenter - " 
repeat; 


: геад. loat 
begin 
pad 1* 80 expect span @ pad c! pad fnumber? not while 
fdrop cr .” Illegal number [float], reenter - ” 
repeat; 


: Setup.curvel ( | dattim - ) 
^ dattim call readdatetime drop ё 
cr .” Today is " 1 .date 
cr ." Setting up parameters for curve 1." 
dettim curvel date s! 
“ lambda” dup сё 1+ curve! wavelength name s^ swap cmove 
T^ dup cê 1% curvel temperature name s^ Swap cmove 
delta” dup cê 1% curvel angle name s^ swap cmove 
[nm]” dup сё 1+ curvel wavelength unit s^ swap cmove 
ІК1% dup сё 1+ curvel temperature unit s^ swap cmove 
191% dup сё 1% curve! angle unit s^ swap cmove 
cr .” Title Cone line) - " cr pad 80 expect 
Span ё curve! title s^ c! 
pad curvel title s^ 1% span 6 cmove 
cr ." Description Cone line) - * cr pad 80 expect 
span @ curvel descriptor s^ c! 
pad curve! descriptor s^ 1+ span 8 cmove 
cr ." lambda [nm] - * read.float curve! wavelength value s! 
сг.” T [K] - “ read.float сигуе1 temperature value s! 
cr ." delta [°] - “ read.float curve! angle value s! 
\ example setup of ‘measurement data’ 
20 9 do 
i i curvel time s! 
i 100 * i curvel counts s! 
loop 


w 
[ 4 
@ 
т 
@ 


cr .“ End setup - “ cr; 


: dump.curvel ( | [ 80 lallot ] mydate - ) 

cr ." Data taken on “ curve! date s@ 1 .date 

cr curvel title s^ count type 

cr curvel descriptor s^ count type 

cr curvel wavelength name s^ count type .” = “ 
curvel wavelength value 56 f. 
curvel wavelength unit s^ count type 

cr curvel temperature name s^ count type .” = ^ 
curvel temperature value sé f. 
curvel temperature unit s^ count type 

cr curvel angle name s^ count type .* =” 
curvel angle value 56 f. 
curvel angle unit s^ count type 

cr .^ data follows:"^ 

20 б do cr 
i curvel time s@ . space 
i curve! counts sé . 

loop 

cr 


Listing 2: Structure definitions from ECFB 
N downloaded from GEnie J. L. Nov 1988 
\ Originally from East Coast Forth Board, 
\ author A. Nonymous 
( This is a set of machforth routines for building records. 
They allow you to build a named record with items of various 
sizes. Executing the record name leaves the record size on the 
Stack, executing an item name leaves the offset of the item 
into the record on the stack. It creates a template for the 
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record but not the actual record. Create the record with “ 
create <name> «record name? allot” or “variable «name? «record 
name? 4 - vallot^ depending if you want the entry in the 
dictionary or variable space ) 


VOCABULARY RECORDS С NEW VOCABULARY ) 
ALSO RECORDS 
DEFINITIONS 


Global 
: Align ( n1 - [nl] or [nl + 1] makes n word aligned ) 
dup 2 mod + ; C USED TO WORD ALIGN 2 & 4 BYTE ITEMS 2 


Global 

' RECORD ( - a 0) 
HERE 4 + CREATE 0 dup M, 
( USED TO OPEN A RECORD ) 


DOES? не; 


Global 
: BYTE: Can - a ni* D 
CREATE DUP W, 1% DOES? We + 


Global 
: BYTES: C a n1 n2 — a п1+п2 | AN ARRAY OF n2 bytes ) 
CREATE OVER Align W, swap Align + DOES» We + 


Global 
: SHORT: Сап! - а п1+2 | 2 byte integer item ) 
CREATE Align DUP W, 2+ DOES» We +, 


Global 
: WORD: C a ni - а п1+2 | 2 byte integer item ) 
CREATE Align DUP W, 2+ DOES» We +, 


Global 

: BOOLEAN: C anl - а п1+2 | 2 byte boolean item ) 
CREATE Align DUP W, 2* DOES? We + ; 

Global 


: SHORTS: Cani n2 – а nl+n2*2 | an array of n2 shorts ) 
CREATE OVER Align W, 2* Swap Align + DOES» We + 


Global 
: LONG: C ani —anit4 | a 4 byte integer ) 
CREATE Align DUP W, 4 + DOES» We + ; 


: HANDLES: ( a ni п2 – a ni*n2*4| array of n2 handles ) 
CREATE OVER Align W, 4 * swap Align + DOES» Wê +, 


Global 
: ADDR: Сап! - a п1+4 | 4 byte address item, 
CREATE Align DUP W, 4 + DOES> W@ + ; 


ie pointer ) 


Global 
: ADDRS: ( ani n2 — a nitn2*4 | array of n2 addresses ) 
CREATE OVER Align W, 4 * swap Align + DOES) We + ; 
Global 
: RECT: Canin2- а п1+8 | а rect item ) 
CREATE Align DUP W, 8 + DOES» We + ; 
Global 
: RECTS: ( a ni n2- a ni*n2*8 | an array of n2 rects ) 
CREATE OVER Align W, 8 х swap Align + DOES? We + ; 
Global 
: STRING: ( a n1 n2 - a ni*n2*1 | a string item n2*1 long ) 
CREATE OVER W, + 1* DOES» We + ; 
Global 
: RECORD: Cani n2- a ni*n2 | а record item of size n2) 
CREATE OVER Align W, swap Align + DOES) We + ; 
Global 
: END.RECORD 
( Mainaddr size -|sets size of struct at a ton) 
Mainaddr W@ Size < 
IF Size MainAddr W! THen ; 
( CLOSES RECORD, STORES RECORD SIZE IN RECORD NAME) 


Global 
: SUB.REC С ) 

CReate 0 W, 2DUP Here 2- Rot Rot DOES» We ; 

( USE TO CREATE VARIANT RECORD ON THE END OF A RECORD) 
Global 


: END.SUB ( SubAddrs MainAddrs Size - ) 
Size SubAddrs W! 
MainAddrs W@ Size < 
IF Size Align MainAddrs W! THen ; 
C USE TO CLOSE VARIANT RECORD ) 


ONLY MAC 
ALSO FORTH 
DEF INITIONS 
ALSO RECORDS 


Global 


Global RECORD Rectangle 
: POINTER: Cani -anit4 | а 4 byte integer ) Global SHORT: Top 
CREATE Align DUP W, 4 + DOES» We + ; Global Short: Left 
Global Global Short: Bottom 
: LONGS: Global SHORT: RIght 
(ani n2 -a nitn2*4 | an array of n2 4 byte integers ) ENd . RECORD 
CREATE OVER Align W, 4 * swap Align + DOES? We +, 
Global Global 
: HANDLE: C ani — a n1+4 | a handle, 4 byte, item ) : rect Variable Rectangle 4 - VALLOT ; - 
CREATE Align DUP W, 4 + DOES» we + ; ( CREATES A RECTANGLE RECORD IN THE VARIABLE SPACE ) sel 
Global IEP 
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Forth Forum Jórg Langowski 
MacTutor Editorial Staff 
System CDEV MACH 2 Volume 5, Number 5 
“System configuration cdev” 10 CONSTANT  keyBoardType 
There is a nice public domain CDEV utility, called S ystat, 12 CONSTANT  atDrvrVersNum 
that shows the system configuration you're running on: machine 14 CONSTANT  sysVRefNum 


type, CPU, floating point hardware, etc. Ever since my last 
system update, this CDEV doesn't run anymore on my Mac II. 
Don't know what I did wrong or what INIT I installed that 
conflicts with it. So to have thatutility back, Idecided to write my 
own - in Mach2 - to give you an example how to write CDEVs 
and how to use the SysEnvirons trap [which is unfortunately left 
unimplemented in Mach 2.14]. 


SysEnvirons 

The Macintosh world has evolved a long way from the one- 
configuration era of the 128K Mac. There are now - at least - 8 
different types of machines on which an application could run, 
the 512K old ROM Mac (yes, some still have one), the Lisa, the 
512KE, Mac Plus, Mac SE, SE/030, Mac II and Mac IIx. I' m not 
counting the ‘small’ MacII with fewer slots since I haven't seen 
that machine as of this writing. 

Add to this variety of machines all the different accessories 
that could be present, such as large screens or accelerator cards, 
and you end up with an impressing array of different configura- 
tions. The confusion is far from being as bad as in the MS-DOS 
world, but it's there; no wonder that some applications start 
having problems running on all possible configurations. 

It is for this reason that the SysEnvirons trap - described іп 
IM V-6 - has been added to the system. This routine returns 
information about the system configuration the program is run- 
ning on, so that you can exit gracefully from your application if 
- for instance - color Quickdraw is needed but not available. 

SysEnvirons accepts two arguments: a pointer to a data 
structure called a sysEnvRec in AO and a version number in DO. 
The version number is used to maintain upward compatibility. 
Right now, two versions of the trap call exist, version 1 and 2, 
which both return the same information. If, at a later time, new 
versionsare defined that return more or other information, the old 
calls can still be used, returning the data in the same old format. 
SysEnvirons returns the sysEnvRec pointer in AO and a result 
code in DO. 

The sysEnvRec, at the moment, has the following fields (in 
Forth notation): 


0 CONSTANT  environsVersion 
2 CONSTANT  machineType 

4 CONSTANT  SystemVersion 
6 CONSTANT processor 

8 CONSTANT  hasFPU 

9 CONSTANT  hasColorQD 
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The fields are described in IM V, but some newer configu- 
rations are not mentioned in the book. As pointed out earlier, 
environsVersion can be 1 or 2 (according to my experimenta- 
tion), but the information returned is the same in both cases. 
machineType can be 0 to 7, because in addition to the MacII, we 
have the Mac IIx, the MacII ‘small version’, and the SE/030 now. 
processor can be 0 to 4, the last value corresponding to the 68030. 

[Incidentally, I know about two otherwise very good pro- 
grams which check the processor type, but don't think about 
Motorola's upward compatibility. TMON at first wouldn't run 
on my IIx, because it doesn't know the processor type returned 
by SysEnvirons. There are processor-specific resources MonC 
and MonI in TMON, and the 68030 requires MonC ID=3 and 
Monl ID=3 to be present. If one simply duplicates the MonC 
ID=2 and MonI ID=2 resources and changes their IDs to 3, 
TMON runs. Languages Systems Fortran, too, has its problems. 
If you compile a program with the 68020 code option on, it won't 
run on a IIx, because that machine has no 68020! Obviously, LS 
Fortran should check for 68020 or greater, and not for 68030 
only. They know about that bug and will revise it.] 

The SysEnvirons trap glue code, and some words returning 
individual values from the sysEnv record, are printed in the 
example. The last part contains some code that you may execute 
from the Mach2 environment and which will print the system 
configuration information directly to the console window. So 
now you know what machine you're using (isn't that great). 


The CDEV 

To put the SysEnvirons information to some practical use, 
we'll write a control panel utility (CDEV) that displays this 
information in the control panel window. CDEVs are described 
in IM V-323, and Steven Sheets has also written an article about 
them (MT V3#10, p.59). ГІІ briefly summarize the relevant 
points. 

A control panel utility is a file of type ‘cdev’ and arbitrary 
creator (we use JLMT, for obvious reasons. Not even registered 
with Apple yet!). The file contains BNDL, ICN# and FREF ID=- 
4064 resources, and a JLMT ID=0 resource, to make its icon 
correctly appear on the desktop. The resources actually relevant 
to the control panel are: 

mach ID=-4064, nrct ID=-4064, DITL ID=-4064, and cdev 
ID=-4064. ‘mach’ determines which machine the CDEV can run 
on; the control panel will display the CDEVs icon on the left side 
of the panel only on machines corresponding to the number 
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contained in ‘mach’ (see IM for details). The “nrct' resource 
contains a number of rectangles that are drawn in the right part of 
the control panel when the CDEV is opened. These rectangles are 
filled with white and framed with a 2-pixel thick black border. 
The rest of the control panel is filled with light gray. After the 
rectangles, the dialog items in the DITL resource are drawn. The 
contents of the DITL are appended to the control panel's own 
DITL. Later when a dialog item on the left hand side of the panel 
is referenced, its item number will have to be incremented by the 
number of items in the control panel's own DITL. 

‘cdev’ contains the actual code for the control panel handler. 
Itis acode resource with its entry point at the very beginning (like 
XCMDs, MDEFs, etc.), and it is called like a Pascal function with 
the following parameters: 


FUNCTION cdev( 
message, item,numItems,CPenelID: INTEGER; 
VAR theEvent:EventRecord; cDevValue: LONGINT; 


CPDialog: DialogPtr):LONGINT; 


Our Forth code has to go through the usual gymnastics to be 
called correctly. We jump from the start of the resource to a piece 
of glue code which saves the old registers, sets up local Forth and 
loop return stacks, and moves the parameters from the A7 stack 
to the Forth stack. The main cdev routine is then called with the 
parameters on the Forth stack (see the listing). message will tell 
the routine what to do on this call. item is the item number of the 
dialog item that was hit; this parameter is only relevant for the 
hitDev message. numltems is the number of items that precede 
the CDEVs DITL in the item list. To address a dialog item from 
its own DITL, the CDEV has to add this number to the item 
number. CPanelID is the resource ID of the control panel DA. 
theEventis a pointer to en event record, valid for hitDev, nulDev, 
activDev, deActivDev and keyEvtDev messages. cdevValue 
contains the return value of the last call of the cdev routine. A 
CDEV might, for instance, allocate its private storage and pass a 
handle to it as a function result; the next time it is called, it will 
find this handle back in the cdevValue parameter. CPDialog is 
the dialog pointer to the control panel dialog. 


CDEV messages 

A CDEV can receive several different messages in the 
message parameter. For our purpose, the initDev message is the 
only relevant one. This message is sent once when the CDEV is 
opened. All we need to do is to find the system information at this 
time and fill in the dialog items so they can be displayed. Once 
this is done, updating of the dialog will be handled by the control 
panel. Other CDEVs might need to handle more messages. The 


allowed values are: 
initDev-0, hitDev=1, closeDev=2, nulDev=3, updateDev-4, ac- 
tivDev=5,  deActivDev-6, keyEvtDev=7,  macDev-8,  undoDev-9, 


cutDev= 10, copyDev=11, pasteDev=12, clearDev=13. 
hitDev corresponds to a mouse down event in control panel 


dialog item. closeDev is sent when the control panel is closed, 
updateDev to keyEvtDev are sent to handle events, and undoDev 
to clearDev are sent when the corresponding Edit menu item is 
selected. 
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nulDev works like the accRun message in a desk accessory; 
it is sent periodically and allows the CDEV to perform actions 
like cursor blinking, time updating, etc. 

macDev is sent optionally on initialization, depending on the 
value of the ‘mach’ resource; when this message is sent, the 
control panel should check whether it can really run on this 
particular machine configuration. 

Our CDEV routine only handles the initDev message. It will 
beep once, and then put string constants corresponding to ma- 
chine type, system version etc. in the various dialog items. It has 
been checked on a Mac 512KE, Mac Plus, Mac SE, SE/030, Mac 
II and IIx. It's up to you to add the checking code for the 64K 
ROM Mac and Lisa. 


Language Systems Fortran and Prototyper 

Even though this is ‘officially’ a Forth column, I'd like to tell 
you some more of my experiences with Language Systems 
Fortran. That system, together with Prototyper, gives you an 
amazingly powerful environment to outfit Fortran programs with 
a nice Mac-ish interface. And you can even have lengthy calcu- 
lations run in the background, if you modify your Fortran code 
slightly. 

I won't describe the program that I’ve been working on in 
detail. Suffice it to say that it's quite long, used for some kind of 
curve fitting, and uses some 2-5 seconds per iteration on a 
Microvax II. It compiles nicely under MPW/LS Fortran, and the 
resulting application runs from a dumb terminal window and 
even gives the same results as the Vax. However. Once started, 
Fortran takes control and releases it only at the very end of the 
program. 50 iterations, 2 seconds per iteration = 100 seconds of 
twiddling thumbs. 

There is an easy way to give some Multifinder compatibility 
to LS Fortran applications. Listing 2 shows a small routine that 
calls WaitNextEvent with an event mask corresponding to up- 
date events and app4 events (context switching). Putting calls to 
this routine in strategic places of your Fortran program, so that it 
is called several times per second, will make the program 
‘background-able’. A mouse click on another application's 
window will switch the Fortran program to the background, 
where it will continue to execute. However, your word process- 
ing, or spreadsheet activity, is slowed down only slightly. My 
pause routine will also set the cursor to a watch when the button 
is pressed inside the Fortran window. That way, the program can 
indicate that it is still calculating, and reset the cursor to an arrow 
when one iteration is done; other routines could at that point grab 
the mouse down event and handle it, to change parameters of the 
calculation etc. 

The second step of making a Fortran program *Mac-ish' is 
to add a real menu/dialog interface for entering and changing the 
parameters to the program. Typically, one would enter file 
names, initial values, matrix sizes, etc. In my particular case, I 
used Prototyper to generate the interface, which gave me Pascal 
code. The Fortran program was split up in convenient subrou- 
tines, which were called as Externals from the Pascal main 
program. 

The strategy was the following: Input parameters, file 
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names, etc. were set via menus and dialogs. When all parameters 


had been set, a menu item could be selected to start the calcula- 


tion. This menu selection would simply set a flag in the Pascal 
program, doCalc. The main event loop's null event handler 
would check this flag and if it was set, run one iteration of the 
Fortran code per event loop. Of course, since each iteration took 
several seconds, this would slow down the user interaction way 
too much. 

Therefore, whenever a non-null event was detected in the 
main event loop, another flag was set which disabled null event 
background processing. This flag was kept on for 5 seconds after 
each non-null event. 

In summary, this strategy will transform your Fortran pro- 
gram into an application that can be juggled into the background 
at any time with 0.1 sec delay and calculate in the background. 
When you click on the application in the foreground, the cursor 
will change to a watch, the current iteration will finish, and then 
you can change parameters, stop the calculation, print intermedi- 
ate results, etc. through the interface provided by Prototyper. 
When no user action is detected for 5 seconds, the program will 
start calculating again. 


French Hacker Story - the End (???) 

You might have followed the story of Faraglace: The French 
hacker who was supposed to pay very heavily for the mistake of 
having removed the copy protection from some programs - 
notably 4th Dimension. He did this out of his own private 
curiosity, the products of this activity got into the hands of some 
pirates, and the whole issue was taken to court. It seems, after the 
result of a recent lawsuit last month, that the story is finally 
coming to a more reasonable conclusion: The total amount of 
fines and damages has gone down from a sum of the order of 
$100,000 to an amount of more like $2,000 (!). This does not 
settle the issue for the pirates who sold the de-protected stuff; 
that's separate. But the fact that a court has recognized that 
cracking and stealing software are not quite the same thing 
relieves me. ACI is still going to appeal this verdict. More to 
come, hopefully good news. 

Till next month, happy threading 


Listing 1: SysConf ig cdev 


\ System configuration cdev 
N Exemple for MacTutor written in Mach2 Forth 
N J.Langowski March 1989 


only forth also mac also assembler 


\ Define SysEnvirons trap; not present in Mach2. 14 
\ alternatively, use the trap compiler accessible on the 
\ GEnie Mach2 libraries and on the V5#1 source code disk 


.TRAP _SysEnvirons %А090 


@ CONSTANT environsVersion 
2 CONSTANT machineType 

4 CONSTANT systemVersion 

6 CONSTANT processor 

8 CONSTANT hasFPU 

9 CONSTANT hasColorQD 

10 CONSTANT keyBoardType 
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12CONSTANT atDÜrvrVersNum 
14CONSTANT sysVRef Num 


N compiler support words for kernel-independent 

V definitions, defproc resources, etc. 

V :xdef compiles a JMP at the beginning of the 

V block, which is resolved at the end of the definition 
V by ;xdef. 


: :xdef € - branch marker ) 
create -4 allot 
$4EFA w, C JMP ) 
Q w, C entry point to be filled later ) 
0, С length of routine to be filled later ) 
here 6 - 76543 ( marker for stack checking ) 


: ,Xdef ( branch marker entry | - ) 
marker 76543 © abort” хде? mismatch” 
entry branch - branch w! 
here branch - 2* branch 2* ! 


: xlen 4 + @ ; ( get length word of external definition ) 


V **** cdev proc glue macros for kernel-independent code 


CODE cdev.prelude 
LINK А6,8-512  ( 512 bytes of local Forth stack ) 
MOVEM.L Ай-А5/00-07,-(А7) С save registers ) 
MOVE.L A6,A3 ( setup local loop return stack ) 
SUBA.L 8256,A3 С in the low 256 local stack bytes ) 
MOVE.L 8CA6), DØ С CPDialog ) 
MOVE.L 12(A6),D1 € cdevValue ) 
MOVE.L 16€A6),D2 С theEvent ) 


CLR.L D3 

МОМЕ .М 2ØCA6), D3 С CPanelID ) 

EXT.L D3 ( in case this is negative ) 
CLR.L D4 

MOVE.W 22(A6),D4 ( numItems ) 

CLR.L D5 

MOVE.W 24(A6),D5 ( Item ) 

CLR.L D6 

MOVE.W 26(A6),D6 ( message ) 


MOVE.L D6,-CA6) 
MOVE.L D5,-(A6) 
MOVE.L D4,-CA6) 
MOVE.L D3,-(A6) 
MOVE.L D2,-(A6) 
MOVE.L D1,-(A6) 
MOVE.L D@,-CA6) 
RTS \ just to indicate the MACHro stops here 
END-CODE MACH 


CODE cdev.epilogue ( resCode - ) 
MOVE.L (A62*,D0 
MOVE .L 00,28СА6) ( store function result ) 
MOVEM.L (A7)+,A0-A5/D0-D7 С restore registers ) 
UNLK A6 
MOVE.L CA7)+,A8 С return address ) 
ADD.W *20,A7 С pop off 20 bytes of parameters ) 
JMP САЙ) 
RTS 

END-CODE MACH 


V the actual cdev code starts here. 

N REMEMBER: don’t use CALL for the toolbox routines; 
V use (CALL) instead, which is not dependent on D4 
V pointing to a correct stack. 


:xdef myCdev 


V just to put some text into the resource 
V for easier identification 
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: start “ Mach2 Forth cdev example, JL/MacTutor 1989" ; 


CODE SysEnvirons 
( theWorld versrequested - theWorld resCode ) 

MOVEA.L 4(A6),A0 
MOVE.L (A62*,D0 
ADDQ.L #4, Аб 
_SysEnvirons 
MOVE.L A®,-CA6) 
EXT.L 00 
MOVE .L D0,-(A6) 
RTS 

END-CODE 


\ words which extract single items from the SysEnvRec 


: ?mach ( | С 12 lallot ] sysEnvRec - machine?! ) 
^ sysEnvRec 1 SysEnvirons drop 2+ wê ; 


: ?sus ( | [ 12 lallot ] sysEnvRec - sustem# revision ) 
^ sysEnvRec 1 SysEnvirons drop 
dup 5 + сё swap 4+ сё ; 


: Iroc ( | С 12 lallot ] sysEnvRec - machinett } 
^ sysEnvRec 1 SysEnvirons drop 6 + wê ; 


: ?fpu ( | [ 12 lallot ] sysEnvRec - machine? } 
“ sysEnvRec 1 SysEnvirons drop 8 + cë ; 


: ?colorQD ( | С 12 lallot ] sysEnvRec - machine® ) 
^ sysEnvRec 1 SysEnvirons drop 9 + cê ; 


: ?кеуТуре ( | [ 12 lallot 1 sysEnvRec - machine? } 
* sysEnvRec 1 SysEnvirons drop 10 + we ; 


: MatkVers ( | [ 12 lallot ] sysEnvRec - machine? ) 
* sysEnvRec 1 SysEnvirons drop 12 + wê ; 


: 2sysVRef (| [ 12 lallot ] sysEnvRec - machine! ) 
^ sysEnvRec 1 SysEnvirons drop 14 + we l ext ; 


A 


factored out the GetDItem/SetIText stuff 


: set.item C string dlgPtr #item ) ( | type hItem box - ) 
^ tupe ^ hItem ^ box (call) GetDItem 
hItem swap (call) SetIText ; 


display system characteristics 

in the cdev dialog box (DITL -4064 resource dependent) 

the strings ere hard-coded, but could as well be contained 
in a STR® resource 


— — — a 


: display.it ( numItems dlgPtr | [ 16 lallot 1 stri - } 
?mach CASE 
0 OF " unknown" ENDOF 
1 OF * Mac 512KE^ ENDOF 
2 OF * Mac Plus^ ENDOF 
3 OF “ Mac SE” ENDOF 
4 OF * Mac II^ ENDOF 
5 OF * Mac IIx^ ENDOF 
\ wasn’t sure whether machine=6 is the new baby MacII, 
N so left out that case 
Т OF “ Mac SE/030^" ENDOF 
* NEW MACHINE" 
ENDCASE  digPtr 3 numItems + set.item 


V get system version # 
V and convert to string, format X.XX 
V if you don’t know Forth, this might be hard to read :-) 
?sys 
* stri swap (call) numtostring 
dup c@ 1+ + swap (call) numtostring 
dup cê 1 = IF dup 1+ сё over 2% c! 
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dup 1+ ascii 0 swap c! THEN 
. Swap c! 

stri dup cê 3 + swap c! 

* stri digPtr 5 numItems + set. item 


ascii 


?proc CASE 
@ OF “ unknown’ ENDOF 
1 OF * 68000” ENDOF 
2 OF ” 68010” ENDOF 
3 ОҒ “ 68020” ЕМООҒ 
4 ОҒ “ 68030” ENDOF 
* NEW" 
ENDCASE dlgPtr 7 numItems + set.item 


?fpu IF “ yes” ELSE ” none” THEN 
digPtr 9 numItems + set.item 


?colorQD IF “ yes” ELSE * no” THEN 
digPtr 11 numItems + set.item 


?keyType CASE 
Ø OF * unknown type” ENDOF 
1 OF “ ‘old’ Macintosh keyboard” ENDOF 
2 OF * ‘old’ Macintosh keyboard with keypad” 
ENDOF 
3 OF “ Macintosh Plus keyboard” ENDOF 
4 OF “ Apple Desktop Bus extended keyboard” 
ENDOF 
5 OF “ Apple Desktop Bus standard keyboard” 
ENDOF 
” something МЕН” 
ENDCASE digPtr 13 numItems + set.item 


^ str1 ?atkVers (call) numtostring 
digPtr 15 numItems + set.item 


: testCdev ( message item numItems CPanel ID 


theEvent cdewalue CPDialog - result ) 
\ we only need to respond to the initDev message 
N by putting the system configuration info 
N into the cdev’s dialog items 
message CASE 
0 OF С initDev ) 1 (call) sysbeep 
numI tems CPDialog display.it ENDOF 
( insert handlers for other messages here) 
ENDCASE 
cdevValue \ everything OK: return old cdevValue 


: cdev.glue 


J 


cdev .pre lude 
testCdev 
cdev.epilogue 


' cdev.glue ;xdef 


N end of cdev code 


N making the cdev resource, the usual way 


: $create-res call CreateResFile call ResError L-ext ; 


: $open-res ( addr | refNum - result ) 


addr call openresfile -> refNum 
call ResError L_ext 
dup not IF drop refNum THEN 


: $close-res call CloseResFile call ResError L.ext ; 


: make-cdev ( | refNum - ) 
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“ cdev.res” dup $create-res 
abort” You have to delete the old ‘cdev.res’ file first." 
$open-res dup -> refNum call UseResFile 
[^] myCdev dup xlen 
call PtrToHand drop ( result code ) 
ASCII cdev -4064 “ cdev JL” call AddResource 
refNum $close-res drop ( result code ) 


2 


N End of cdev creation code. 
V Following are some words that can be executed 
V from within the Mach2 sustem, and output 
\ system configuration information directly to the console. 
: myMachine cr .^ This is а” 
?mach CASE 
0 OF ." n unknown machine,” ENDOF 


1 OF .” Mac 512KE,” ENDOF 
2 0F ." Mac Plus," ENDOF 
З OF .^ Mac SE,” ENDOF 
4 OF ." Mac II,” ENDOF 
5 OF .” Mac IIx,” ENDOF 
Т OF ." Мас SE/030,^ ENDOF 
.” NEW MACHINE," 
ENDCASE 


: mySystem ?sys 
.” running system v. ” 
«8 8 8) type ascii . emit 
«€ 8 8 8) type ascii . emit 


: myProcessor cr .^ It uses a” 
?proc CASE 
0 OF ." n unknown? ENDOF 
1 ОҒ.” 68000" ENDOF 
2 OF .^ 68010" ENDOF 
3 ОҒ.” 68020" ENDOF 
4 OF .^ 68030" ENDOF 
." NEW” 
ENDCASE 
." processor” 


: myFPU ?fpu IF 
escii , emit cr 
.” end has an arithmetic coprocessor installed." 
ELSE 


ascii . emit 
THEN 
: myCQD cr .^ Color QuickDraw is ” 


?colorQD б= IF 
." available.” 


." not * THEN 


: myKeyBoard cr 


: myAtkDrvr cr 


." The Keyboard is “ 


?keyType CASE 


0 OF ." of an unknown type.^ ENDOF 
J OF ." the ‘old’ Macintosh type.” ENDOF 
2 OF ." the ‘old’ Macintosh type with keypad.” ENDOF 
3 OF .^ the Mac Plus type.” ENDOF 
4 OF .^ the ADB extended type.” ENDOF 
9 OF .^ the standard ADB type.” ENDOF 
." а NEW type.” 
ENDCASE 


." Appletalk v. " ?atkVers . 


.? is installed." 


: machTest 
myMachine mySystem 
myProcessor myFPU 


2 


myCQD 


myKeyBoard 
mgAtkDrvr 


cr 


Listing 2: Language Systems Fortran background enabler 


ооо о 


subroutine pause(sleep) 
! In Inlines.f 
integer*4 sleep 


call Waitnextevent to generate a pause. 
Sleep parameter in ticks. 


will discard all Multifinder events (update, Suspend/Resume) 
cursor to watch if button is pressed 


and set 


include 
include 
include 
include 


f 
f 
f 
f 


: :f includes :Memtypes.f’ 
: :f includes : Quickdraw. f ’ 
: :fincludes:0SIntf .f’ 

: :fincludes:Toolintf .f ° 


record /eventrecord/ myEvtRec 
record /CursHandle/ myCurs 
logical*1 p 


р = waitnextevent (SvalCupdateEvt*app4Evt), 
Sref(myEvtRec), $valCsleep), %у81(0)2 


if (button) then 
myCurs.CrsrH = getCursor($val(watchcursor 22 
call setCursor(%val(myCurs.CrsrH*.CrsrP)) 


end if 


return 
end 
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“INITs and trap patches” 

This month’s program started off as an attempt to write a 
‘logging’ utility, that is, a routine that will record when applica- 
tions are launched and closed. Simple, I thought. Just patch the 
 Launchand ExittoShell traps and install some code that writes 
a line to a file giving the time, date and name of the application 
each time these traps are called. However, I soon realized that it’s 
not as simple as that. Under Finder, yes, that strategy works; but 
imagine my surprise when I found that Launch is never called 
when an application is started under Multifinder! This ‘feature’ 
seems not to be documented in the technical notes that I have, nor 
in the Multifinder documentation. 

If you record trap calls with TMON, you'll find the follow- 


ing sequence for launching an application under Finder: 
-Launch 
-LoadSeg 
-LoadSeg 


. Cuntil all necessary segments are loaded) 


and for exiting, ExittoShell is called. Multifinder seems to 
use the same sequence of calls, except for the first call to 
Launch, which is left out. 

Therefore, if we want to build a routine that logs application 
launches, we have to find another indicator. One trap call is 
always made when an application is started:  GetResource is 
called for CODE ID=0. If we patch GetResource such that this 
particular call is intercepted, we have a ‘hook’ that allows us to 
install any routine to be called at application startup. 


Patching traps under Multifinder 

Traps cannot be easily patched in a permanent way under 
Multifinder. Since different application might need different trap 
patches, Multifinder intercepts (I believe) SetTrapAddress and 
switches the trap patches when control is transferred from one 
program to another. So, when you write a short application that 
patches a trap, that patch will only be valid in the context of that 
application - and disappear when the application quits again. Not 
very useful for a routine that logs application launches, which 
will have to work independently of any particular context. So 
we'll have to install the patch before Multifinder is started, and 
this is best done with an INIT. 

This month's example will show you how to write an INIT 
under Mach2 that installs permanent patches to _GetResource 
and ExittoShell. For the moment, all these patches do is beep 
once when the application starts and when it quits. These patches 
would then have to be extended to write some text to a file that 
gives the name and time of the application. 

I'll also give an example of a small application that can be 
used to run an INIT from a file in the same folder as the 
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application. It uses the same mechanism as the system itself to 
call the INIT. This program is based on an idea of Eric Carrasco 
from the Calvacom bulletin board in Paris, who wrote a similar 
program in Pascal. 


The INIT 

The mechanism by which an INIT resource is called has 
been outlined already by Bob Denny in V1#9. In case you're 
missing that issue, I'll quickly repeat it here: First, the INIT 
resource is loaded into the system heap. Then, DetachResource 
is called which tells the resource manager to forget this resource. 
Finally, the system jumps to the first location of the INIT 
resource via a JSR. When the INIT later returns via RTS, the first 
two words in its code are overwritten by NOP instructions. The 
reason for this procedure, which might seem a little strange, is 
that an INIT code might consist of a JMP to some installation 
code at the end, and have the actual memory-resident part at its 
beginning. That way, when the JMP at the beginning is overwrit- 
ten by NOPs, any code that jumps to the start of the INIT will now 
execute its main part. The initialization part at the end can be 
given back to the memory manager, once the INIT is installed. 

Listing 1 shows the INIT code in Mach2. The kernel- 
independent code is produced in the usual way, using the external 
definition words which make sure the JMP at the first location if 
the INIT points to the right piece of code, and which set up the 
local Forth stack. 

The INIT (word INITrun) first creates a handle to its own 
memory block by calling  RecoverHandle, then locks this 
handle. A temporary area for the Quickdraw globals is then 
created in the local variable space. Remember that local variables 
in Mach2 are allocated from top to bottom in memory, so that the 
sequence 


newA5 myGlobals [ 202 lallot ] 


with A5 later pointing to the address of newAS will have the 
QD globals allocated correctly below A5. If your INIT needs to 
use any of them, simply reference them starting at myGlobals. 

Our INIT code sets up AS and the low memory global 
CurrentA5, then calls the usual manager initialization traps 
necessary for setting up a dialog box. After these calls, the 
environment is ready for calling the main Forth code of the INIT, 
myINIT in our case. From myINIT, all toolbox traps may be 
used since А5 points to valid QD global space and the managers 
have been initialized (oh... not the menu manager, of course, but 
you probably wouldn't want to use menus from an INIT. I doubt 
whether it would be possible, anyway. Try it out). 

For an INIT that is supposed to stay in the system heap “ав 
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is’, you don’t need to take any special action in the code to free 
its memory space. However, when - as in our case - the INIT 


copies part of itself to a non-relocatable block in the system heap 


and is not needed anymore, we want to purge the memory space 
after action. This is done by calling DisposHandle after my- 
INIT has returned. 

gINIT is the glue code that calls the standard ‘INIT 
interface’ INITrun. Here, the registers are saved, stacks are set 
up, and CurrentAS is restored after INITrun has returned. 

The main INIT code, myINIT, first moves the patch code 
into a non-relocatable block in the system heap. It then patches 
_GetResource, using  SetTrapAddress, and moves a vector to 
the trap's old address into the appropriate location inside the 
patch. The user is notified of the patch by an alert. Тһе GetRe- 
source patch itself (GetResPatch) checks whether this trap has 
been called with resource type CODE, ID=0. In that case, it beeps 
once. Instead of the beep, one could insert some code that writes 
alinetoa file which has been opened in the installation part of the 
INIT. Something left as an exercise... 

There is also a patch to ExittoShell, ExitPatch, which is 
supposed to beep when an application quits. Now look at the code 
where the INIT installs that patch. We do a_GetTrapAddress, 
right, but then the ugly part starts. If ExittoShell is patched by 
_SetTrapAddress at system INIT time, the patch gets installed 
correctly, and you hear the beep when the Finder quits and calls 
the Multifinder, but then, silence. The patch has disappeared. 
Multifinder patches  ExittoShell as well and probably doesn't 
conserve previous patches. I don’t know whether this is a bug or 
a feature (such as not calling Launch when starting an applica- 
tion); but it makes life a great deal more difficult. Apple, can you 
hear me? 

Here’s the workaround that I thought up, which works under 
System 6.0.2, and is not guaranteed to work under a new release 
(no, don’t leave the room yet, PLEASE!). When Multifinder 
patches _ExittoShell, it installs a JMP instruction to its patch code 
in RAM. Our INIT code tests whether the pointer returned by 
_GetTrapAddress points to a JMP «absolute» instruction. In that 
case, it patches the next two words with a pointer to our patch 
code and saves the old JMP address in the patch code. If the first 
instruction is not a JMP «absolute», we assume we're running 
under Finder and use _SetTrapAddress to patch the trap. Ugly, 
isn't it. The worst part is that if you run under Multifinder your 
patch will be installed and then removed again; then you have to 
run the INIT again under Multifinder to install the ExittoShell 
patch permanently. But I couldn't find an easier way, please tell 
me if you have one. 

How can you run an INIT at all when Multifinder runs 
already? This is where the short runINIT application comes in 
(Listing 2). This program will simulate the way the system calls 
an INIT resource. It will locate the file ‘theINIT’ which must be 
in the same folder, get the INIT ID=12 resource from that file and 
execute it the same way the system boot code would do it. So for 
installing the _ ExittoShell patch under Multifinder, you simply 
double-click runINIT in the system folder, or make it one of your 
startup applications. 
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INIT incompatibilities 

Our INIT is also a practical case where we can document that 
frequent disease of Mac system folders, INIT incompatibility. 
This INIT calls all the toolbox managers necessary to set up an 
alert, and then actually displays one. That means, WaitNextE- 
vent will be called from the alert. Other INITs might patch 
 WaitNextEvent, GetNextEvent or SystemTask to take some 
action when the system is fully booted up. That way, for instance, 
the ‘Remember’ INIT seems to call its associated desk accessory 
when some important dates are coming up. The problem is, when 
Remember is executed before an INIT that displays a dialog, the 
patch will open the desk accessory, which produces disaster in 
form of a bomb box. 

I guess this incompatibility will always occur when you have 
one INIT which patches _SystemTask or similar routines to 
execute some other application or DA later on. If another INIT 
happens to call the patched trap and the system is not ready yet 
for whatever the first INIT wanted to be executed, a crash will 
probably follow. Make sure that this INIT is executed before any 
INITs that patch WaitNextEvent, GetNextEvent or _Syste- 
mTask. 


Mach2 news 

Finally I want to advertise the GEnie Mach2 and FIG round 
tables again. There is simply more interesting stuff in the soft- 
ware libraries than I could ever discuss here; the Mach2 system 
has been extended by hundreds of useful words already (by the 
way, v2.15 is on its way), and you find more in the FIG Forth 
libraries. Especially with the ANSI Forth standard coming up, a 
lot of the discussion on that new standard - and its implications 
on Mach2 - takes place on GEnie. For those of you who can't 
access GEnie, but have access to Bitnet directly or via a gateway, 
ГІ try to get a compilation of the most important new words to 
you if you send me electronic mail: 

LANGOWSKI@FREMBLS1.BITNET 

Happy threading. 


Listing 1: Trap patch INIT 
\ INIT example which patches _GetResource 
V with а call to _Sysbeep if type=CODE id=0 
V Also patches .ExitToShell, using an absolutely 
\ AWFUL hack, but a _SetTrapAddress patch 
\ seems to be removed under Multif inder 
\ J. Langowski / MacTutor April 1989 
only forth also mac also assembler 
( *** compiler support words for external definitions *** ) 
: ixdef 
create -4 allot 
$4EFA w, C UMP ) 
0 ш, C entry point to be filled later ) 
0, € length of routine to be filled later ) 
here 6 - 76543 


: ,Xdef ( branch marker entry | - ) 
marker 76543 © abort” xdef mismatch” 
entry branch - branch w! 
here branch - 2+ branch 2+ ! 


: xlen 4 + ё; ( get length word of external definition ) 
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V **** ext procedure glue macros 


CODE ext.prelude 
LINK A6,4-700 С 700 bytes of local Forth stack ) 
MOVEM.L А0-А5/00-07,-САТ) ( seve registers ) 
MOVE.L A6,A3 ( setup local loop return stack ) 
SUBA.L 8500,АЗ С in the low 200 local stack bytes ) 
RTS N just to indicate the MACHro stops here 
END-CODE MACH 


CODE ext.epilogue 
MOVEM.L СА72%,А0-А5/0р0-07 С restore registers ) 
UNLK A6 
RTS 

END-CODE MACH 


(Агар .newPtr,SYS$A51E 


-4 CONSTANT thePort 

$904 CONSTANT CurrentA5 

$A9A9 CONSTANT tGetRes N GetResource 
$A9F4 СОМЅТАМТ tExit — X ExitToShell 


\ | INIT resource code starts here | 
\ = = сы 


:xdef beeper INIT 


header PatchStart 

header oldGetRes 
DC.L Ø 

header oldExit 
DC.L 0 


: GetResPatch 
ext.prelude 
CLR.L DØ 
MOVE.W 8CA62,D0 
MOVE.L 19CA62,D1 
MOVE.L D0,-CA6) 
MOVE.L D1,-CA6) 


main FORTH code starts here 

this can be used to log anu launch 

(i.e. GetResource CODE 0 ) to a log file 

which has to be created/opened by the INIT code 


A — — — 


ascii CODE = swap 0- and IF 
V (call) debugger 
1 (call) sysbeep 
THEN 
end of main code 


т 


ext.epilogue 

LEA oldGetRes,A0 
MOVE.L CAO), AO 

JMP (A0) 


; ExitPatch 
ext.prelude 


N main FORTH code starts here 
V this can eventually be used to write a line to 
V the same log file as before 
\ (call) debugger 
1 (call) sysbeep 
\ end of main code 


ext .epi logue 

LEA oldExit, АЙ 
MOVE.L CA02,A0 
JMP (Ag) 
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header PatchEnd 


: movePatch ( | length - patch ) 


(71 patchEnd [^] PatchStart - -> length 
length 
MOVE.L CA62*,D0 
-newPtr,sys 
MOVE.L A®,-CA6) 
dup IF ( we have space in system heep ) 
(71 PatchStart over length swap 
(call) blockMove drop 


THEN 


: myINIT ( | patch pExit - ) 


movePatch -> patch 
patch IF 
N patch _GetResource 
tGetRes (call) GetTrapAddress 
patch ! \ old GetResource 
(71 GetResPatch [°] PatchStart - 
patch + tGetRes (call) SetTrapAddress 
“ GetResource patch has been installed." 
0 0 0 (call) ParamText 
1000 0 (call) NoteAlert drop 


V patch _ExitToShell, using hack 
tExit (call) GetTrapAddress -» pExit 
pExit we $4EF9 = 
IF N is it a MP «absolute? 
N ? we're probably in Multifinder... 
pExit 2+ @ 
patch 4+ ! \ old ExitToShel1 
(41 ExitPatch (^J PatchStart - 
patch * pExit 2* ! 
V patch directly into Juggler’s innards. BOO! 
* ExitToShell patch in Multif inder. ” 
0 0 0 (call) ParamText 
1000 0 (call) NoteAlert drop 
ELSE 
pExit patch 4+ ! 
(^] ExitPatch ['] PatchStart - 
patch + tExit (call) SetTrapAddress 
* ExitToShell patch in Finder." 
0 0 0 (call) ParamText 
1000 0 (call) NoteAlert drop 
ТНЕМ 
ELSE 
“ Can’t get memory for patches.” 
0 0 0 (call) ParamText 
1000 0 (call) NoteAlert drop 


THEN 


: INITrun ( | newA5 muGlobals [ 202 lallot ] theHandle - ) 


(call) debugger 

[°] beeperINIT (call) recoverHandle -> theHandle 
theHandle (call) Hlock drop 

^ пенА5 

MOVE.L CA6)+,A5 \ create area for QD globals 
MOVE.L A5,CurrentA5 N А5 points to it 

^ newA5 thePort + (call) InitGraf 

(call) InitFonts 

(call) InitWindows 

(call) TEInit 

0 (call) InitDialogs 

(call) InitCursor 


myINIT \ call main INIT routine 


theHandle (call) HUnLock drop 
theHandle (call) DisposHandle drop 
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; \ which he implemented in Pascal 
: $open-res ( addr | refNum - result ) 
: gINIT addr call openresfile -> refNum 
ext.prelude INITrun ext.epilogue call ResError L_ext 


MOVE.L A5,CurrentA5 dup not IF drop refNum THEN 


2 


-` 


gINIT ;xdef : $close-res call CloseResFile call ResError L_ext ; 


*** creating the INIT file *** ) 


oo 


$4E7 14E71 CONSTANT nopnop 


: $create-res call CreateResFile call ResError L ext ; 


: $open-res ( addr | refNum - result ) 
addr call openresfile -> refNum 
call ResError L.ext 
dup not IF drop refNum THEN 


: $close-res call CloseResFile call ResError L.ext ; 


: make-init ( | refNum - ) 
* theINIT^ dup $create-res drop 
$open-res dup -? refNum call UseResFile 
ascii INIT 12 call GetResource 
?dup IF call RmveResource THEN 
['] beeperINIT dup xlen 
call PtrToHand drop ( result code ) 
ascii INIT 12 call GetResource 
?dup IF call RmveResource THEN 
ascii INIT 12 ” Beeper” call AddResource 
refNum $close-res drop ( result code ) 


д 


Listing 2: INIT runner application 
\ INIT 12 starter 
\ J. Langowski / MacTutor April 1989 


N Thanks to Eric Carrasco (Calvacom ЕС10) to this idea 


bye 


: runINIT ( | refNum hINIT - } 


* theInit^ $open-res -> refNum 
refNum @ > IF 
ascii INIT 12 call GetResource -? hINIT 


hINIT IF 
hINIT call HomeResF ile 
refNum = IF 


hINIT call DetachResource 
hINIT @ execute V run the INIT 
nopnop hINIT e ! 
V fill first 2 words with NOPs 
ELSE 
* INIT not from my file" 0 0 0 call ParamText 
1000 @ call NoteAlert drop 
THEN 
ELSE 
* Can't find INIT 12 resource” 
@ 0 0 call ParamText 
1000 0 call NoteAlert drop 
THEN 
ELSE 
* Can't open file ‘theINIT’” 0 Ø Ø call ParamText 
1000 0 call NoteAlert drop 
THEN 
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Forth Forum 
Appletalk Protocol Handlers 


“Appletalk protocol handlers” 

Many of you may have used Appletalk in one or the other of 
their programs, but the way it really works is an interesting 
mystery to most of us. Since a recent project of mine will have to 
use some of the low-level features of Appletalk, I'd like to 
describe some of the hooks built into it that allow you to set up 
your own network protocols or change those provided by Apple. 

Long-time readers of MacTutor will remember that we had 
a series of articles on Appletalk in V1#10 and #11 already; also 
one of my Forth columns (V4#9) showed some examples how to 
use the Appletalk services from Mach2. All these articles were 
mainly dealing with the high-level features of Appletalk, ATP 
and higher. The way the low-level stuff works was more or less 
taken for granted, and that’s the way 95% of all programs would 
normally use Appletalk. Why and when do we have to take a 
closer look? 

Imagine, for instance, a program that implements a bridge 
between two Appletalk networks. One may be the Localtalk 
connection that your Mac is hooked up to through the serial port, 
the other the Ethernet that you have plugged into your Ethernet 
card. Apple's Network CDEV lets you change from one network 
to the other, but you can't (yet) choose two networks simultane- 
ously. Infosphere's LIAISON™ , however, allows you to do just 
that, bridging Localtalk and Ethernet by a process that runs on 
your Mac in the background. Thus, there exists at least one 
example to show that an Appletalk bridge can be implemented as 
a background process on the Mac. (The other solution, of course, 
being a hardware box like Kinetics' FastPath or the Gatorbox). 
Such programs must use the Appletalk routines at a lower level; 
and I'll give some examples how to do that in the following. 


DDP packets 

Remember how internet addressing works on Appletalk: 
Eachlocal network has a unique network number, each device on 
the network a unique node number, and each separate process on 
the device a unique socket number. 

Whena process on the Mac (e.g. a word processing program) 
wants to communicate with another device on the network (let's 
Say, a printer), it will first look up its internet address using the 
name binding protocol described in the articles mentioned above. 
Once the internet address is known, it can then send out a packet 
to the remote device over the network or receive packets from it. 
The two devices can be either on the same local network, or on 
two different networks that are connected through bridges. 
Depending whether the remote device is on the same local 
network or not, the Appletalk driver will send your data to the 
network in either of two different formats. You normally don't 
see the difference; the datagram delivery protocol (DDP) takes 
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care of checking whether the destination network number is the 
same as your own network number or not. The two different 
formats are called long or short DDP packets, and their format is 
shown in Fig. 1. 


length field 
(10 bits) 


destination socket # 


source socket # 


hop count (4 bits) + 
length field (10 bits) 
DDP checksum 
destination 
network # 
source 
network # 


data (O to 
586 bytes) 


DDP protocol type 


data (O to 
586 bytes) 


Fig.1 : short (left) and long (right) DDP packets 
Typically, when the two communicating nodes are on the 
same local network, DDP will send short packets. When the two 
nodes are on different networks, DDP will send long packets; 
also when the two nodes are on the same network, but the sending 
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node doesn’t know its own network number. In that case it will 
set the source network number of the packet to zero and send a 
long packet anyway. 

The first two header bytes after the flag bytes (destination 
and source node #) determine the two nodes on the local network 
that communicate with each other. Ina short packet, the destina- 
tion node number is the number of the final node of the commu- 
nication link. However, for a long packet that is routed through 
a bridge, the immediate destination node is that bridge; therefore 
the first header byte contains the bridge’s node number and the 
final destination is given further down in the packet. 

The distinction between the two packet formats is made in 
the third byte of the header, the LAP protocol type. LAP stands 
for link access protocol, the lowest level of the Appletalk proto- 
col which delivers data from one node to the other on the same 
local network. The LAP protocol then determines what to do with 
the packet after is has been received. 


Node addressing 

There is a lot of traffic going on on a typical Appletalk 
network, and each node has to filter out only those packets that 
it needs to receive, that is, those where the destination node ID 
matches its own ID, or where the destination ID is $FF (broadcast 
packets). This is a task that has to be done by dedicated hardware. 
We cannot expect the Macintosh CPU to look at each single 
packet and see whether it has the correct ID; doing that, we 
wouldn’t have time for doing any other work. 

Fortunately, the Macintosh’s 8530 SCC chip (serial commu- 
nications controller) can be programmed to automatically detect 
а flag byte - а 01111110 sequence - followed by an address byte 
- the destination address -, and send an interrupt only if the 
received address matches a preset value. That way a node will 
ignore all packets except those that it is actually supposed to 
receive. 


LAP protocol handlers 

Now, a packet is arriving that carries the correct node 
number in its header, what are we going to do with the data? 
Whatever we do, we should do it fast, because data is arriving at 
arate of 260 KBaud. The SCC's internal buffer holds three bytes, 
so we have only 95 ps to take any action required. The decision 
what to do with the packet depends on the value of the third 
header byte, the LAP protocol field. Each packet structure (DDP 
long/short, other structures that you might have implemented) 
corresponds to a different protocol number. 

For each protocol number that the node understands, there 
will be an entry in a protocol handler table consisting of the 
protocol number and the handler's address. The low-level packet 
reception routine will search the table for the protocol number, 
and transfer control to the corresponding handler if it is found. 
Otherwise, the packet will just be ignored. 

. The protocol handler table is located іп the Appletalk global 
variable area; the address of this area is kept in the low-memory 
global ABusVars ($02D8). The structure of the Appletalk global 
variable area is described in part in Inside Macintosh II-328, the 
protocol table is not specified there. This is because the format of 
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the protocol table depends on the specific Appletalk implemen- 
tation, the MPP driver in the System file expects a different 


. format than that in ROM. As an example, I'll give the format for 


the MacII (and SE) when Appletalk has been loaded from ROM: 


О sysLAPAddr This node ID (byte) 

1 toRHA read header area (24 bytes) 

25 sysABridge Node ID of a bridge on the 
local network (byte) 

26 sysNetNum This network number (word) 

28 vSCCEnable status register value to 
re-enable SCC interrupts 
(word) 

ee (some unspecified bytes) 

36 LAPprotNums LAP protocol numbers 
(8 bytes) 

44 LAPprotProcs LAP protocol handlers 


(32 bytes = 8 pointers) 

Each entry in the protocol table is either a protocol number 
at (36+1) and a corresponding address at (44 + 4*i) with iO to 7, 
or $FF and a zero address for free slots in the table. We see that 
a maximum of eight different protocols are allowed; this is 
because checking of the protocol type and control transfer to the 
handler must be completed in the allowed time frame of 95 us. 

Thus, when the protocol number of the packet corresponds 
to a valid protocol handler in the table, control will be transferred 
to that protocol handler. This month's example program contains 
a protocol handler that can be installed instead of the default 
handler for long DDP packets (LAP type 2). A warning in 
advance: Installing this handler will completely screw up most of 
your Appletalk services, since your Mac won't understand long 
DDP packets correctly anymore. 

The default DDP protocol, after reading the packet header 
(Fig. 1), gets the address of a socket listener routine from the 
socket table, where socket numbers and listener routine pointers 
are arranged similar to the protocol handlers in the protocol table. 
The socket table is also kept in the ABusVars block pointed to by 
A2. The default protocol handler transfers control to a socket 
listener if it finds one in the table. For long DDP packets, we will 
now replace the default handler by one that simply reads the 
packet data into a buffer and does nothing else. You may then - 
from Масһ2 - look at the packet data in the buffer. To restore 
normal Appletalk operation, you must disable and re-enable 
Appletalk from the Chooser. This restores the default handlers. 

The new handler code is defined in the word myLAP2. 
When a packet arrives, it will first verify whether the destination 
network is the local network. If so, it will read the packet data into 
a buffer which is located just in front of the handler code. It will 
thenconstructa short DDP packet out of the long one by stripping 
all the network information. This packet could then be re-sent to 
the network; setting the SetSelfSend flag to true, the same node 
would receive it again, this time through the LAP type 1 protocol 
handler. The corresponding code is commented out, since it did 
not work for me in this simple manner. So far, the protocol 
handler can only be used to look at the raw packet data. ГЇЇ keep 
you informed when I've found the reason why. 

attach.ph and detach.ph are used to insert and remove 
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handlers in the protocol table. A handler can only be attached to 
a protocol type if that type is not yet present in the table; therefore 
to change the LAP type 2 handler we have to remove the old one, 
then install the new one. change.prots gets a block in system 
heap space, moves the handler code with the buffer areas into that 
block, and installs the new protocol handler. 

This almost concludes my short introduction into low-level 
Appletalk stuff; a lot of the information presented here is not 
documented in any Apple documentation that I’m aware of and 
could only be found out by disassembling into ROM. Disassem- 
bly also showed me the function of two more Appletalk system 
globals, the procedure pointers ATalkHk1 ($B14) and AT- 
alkHk2 ($B18). Both are active when they are non-NIL: AT- 
alkHk1 seems to be called on each Control call to the .MPP 
driver, and ATalkHk2 on every writeLAP call. ATalkHk2, in 
particular, would enable you to define alternate link access 
protocols, as for Ethernet, ISDN, and the like (for more detail on 
this, see the Alternate Appletalk Connections Reference, APDA 
#KNBO007). 


Listing 1: LAP protocol handler exemple 
only forth also assembler 

\ Appletalk LAP protocol handler example 

N 12.05.89 JL 

$904 constant currentA5 


DECIMAL 


12 constent ioCompletion 
18constant ioFileName 
18constant userData 
24constent ioRefNum 
26constant csCode 
27constant ioPermission 
28constant socket 

28 constant protType 

30 constant addrBlock 

38 constent handler 


9 constent mppUnitNum 
mppUnitNum 1* negate 
constent mppRefNum 


V LAP defs 

1 constant LAPshor tDDP 

2 constant LAPLongDDP 

-94 constant lapProtErr 

-95 constant lapExcessCol Ins 


243 constant lapWrite 
244 constant lapDetachPH 
245 constant lapAttachPH 


-Iconstant lapOverrunErr 
-2constant lapCRCErr 
-Qconstant lapUnderrunErr 
-4constant lepLengthErr 


N DDP defs 
5 constant ddpHdSzShort 
13constant ddpHdSzLong 


1 constent ddpRTMP 
2 constant ddpNBP 
3 constant ddpATP 


$7F constant ddpMaxWKS 


586 constant ddpMaxData 
$3f f constant ddpLengthMask 
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12 


-9 
-9 
-9 


A 
24 
24 


8 constant ddpWKS 


1 constant ddpSktErr 
2 constant ddpLenErr 
3 constant ddpNoBr idgeErr 


CsCode values for DDP Control calls- MPP 
6 constant ddpWrite 
7 constant ddpCloseSkt 


248 constant ddpOpenSkt 


256 constant setSelfSend 


$1FA constant pRamByte 
$1FB constant SPConf ig 
$291constant portBUse 
$208 constant ABusVars 
$20C constant ABusDCE 


X ABusVars block 
0 


1 
8 
25 
26 
28 


һе 
һе 
һе 
һе 
4% 
t 
CO 


A — өт т т өт” — т лт” 


\ 


constant sysLAPAddr 
constant toRHA 

constant dstNetNum 
constant sysABr idge 
constant sysNetNum 
constant vSCCEnable 


ader handler.start 

ader ATPblock 50 allot 
ader LAP block 8 allot 
ader packet 586 allot 


rap -control,async $8404 
rap -newptr,sys  $851E 
DE myLAP2 

moveq.] #ddpHdSzLong-2,D3 
move.w sysNetNumCa2),D2 
jsr (a4) 

bne 62 

cmp.w ds tNetNum(a2),d2 
bne e1 

lea packet ,a3 

поуе.1 8586,03 

jer 2(a4) 

bie 802 

lea LAPiblock,a0 


move.b toRHACa2), (ай) \ dest node ID 
move.b toRHA+1(a2), 1(að) X source node ID 
move.b 81,2(а0) V LAP type = 1 

move .b toRHA*3Ca22,3Ca0) \ length field MSB 
move .b toRHA*4Ca22,4Ca0) \ length field LSB 
move .b toRHÁ*13(822,5C(a0) NX dest skt number 
move .b toRHA+14(a2),6(80) \ src skt number 
move.b toRHA*15(a22,7Ca0) \ DDP prot type 
-debugger 

set up parameter block for LAPwrite call 

lea — ATPblock,a 

move.w ®mppRefNum, ioRef NumCa2) 

поуе.1 80 ioCompletionCa2) 
move.w ®LAPwrite, csCode(a@) 
lea LAP Iblock,al 

move.1 al,addrBlock(a0) 
move.w vSCCEnable(a2),sr 
-control,async 


\ re-enable interrupts 


@2rts 


ê 1moveq.1 


80,d3 


jmp 2(а4) 


END-CODE 
header handler .end 
: call.mpp 


mppRefNum  ['] ATPBlock ioRefNum + w! 
(71 ATPBlock call contro! 


: ettach.ph С protType handler - flag ) 


€ handler ) ГС“) ATPBlock handler + ! 
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С protTupe ) С°] ATPBlock protTupe + c! 
lapAttachPH (“] ATPBlock csCode + w! 
call.mpp 


: detach.ph € protType - flag ) 

( protType 2 [^] ATPBlock protType + c! 

lepDetachPH  ('] ATPBlock csCode + w! 
call.mpp 


: set.self.send С self send. flag | old_flag - ) 
setSelfSend 171 ATPBlock csCode + w! 

C flag ) [*] ATPBlock 28 + c! 

call.mpp drop N result code 

(71 ATPBlock 29 + ce 


: get.sys.block 

(71 handler.end [^] handler.start - 

MOVE.L CA62*,00 

-newptr,sys ( get memory block in system heap ) 
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MOVE.L AQ,-(A6) 


: chenge.prots ( | protPtr - ) 


get.sys.block -> protPtr 
protPtr IF 
(71 hendler.start protPtr 
[°] handler.end [^] handler.start - cmove 
2 detach.ph 
abort” Could not detach protocol handler” 
2 [°] myLAP2 (71 handler. start - 
protPtr + 
attach.ph 
abort” Could not attach protocol handler” 
255 set.self.send drop 
ELSE .^ Could not get memory for protocol handler” 
THEN 


cr .” Buffer area is at “ protPtr 50 +. cr 
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Basic School 


Time Retrieval and Storage Techniques 


Time Retrieval and Storage Techniques 

It’s only a matter of time. Anybody see the ad for the 
MacTutor of the future in the November, 1988 MacTutor? The 
ad may sound like a joke about the 100th anniversary of MacTu- 
tor, but some of the “future” has already been invented. I did 
some thought on the subject of the Basic School column de- 
scribed in the ad, which is also the title of this column. There are 
two basic subjects implied by the title, time retrieval and time 
storage. 

From a philosophical point of view you may ask, how can 
time be saved or retrieved? Looking at the answer from that 
perspective would lead us to a discussion of Einstein and his 
theory of relativity which is beyond the scope and intent of this 
column. Instead let’s look at some ways which we can use time 
to our advantage and see how storage and retrieval fits into the 
scheme of things. 

From a user level on the Macintosh there is one time 
retrieval/storage mechanism that is accessible to all “the rest of 
us”. The example I refer to is the Alarm mechanism built into the 
clock chip. The date and time setting is copied (“retrieved”) at 
system startup from the clock chip into its own low-memory 
location. It’s stored there as the number of seconds since 
midnight, January 1, 1904, and is updated every second. The 
range of the clock chip is from January 1, 1904 through February 
6, 2040 (does that mean that 51 years from now ГЇЇ need to 
replace my clock chip?). The low-memory location can be access 
by your program. BASIC (every brand) includes its own time 
retrieval command. In True Basic the TIME and TIMES func- 
tions are provided. TIME returns the number of seconds since 
midnight in tenths of seconds. The TIMES function returns a 
string that contains the time as measured by the 24-hour clock 
with resolution in seconds. ZBasic and MS QuickBASIC uses 
the TIMER function which returns the seconds since midnight 
(similar to the True Basic TIME function) and TIMES which 
works the same as in True Basic. The problem is that the TIMER 
function does not provide enough resolution. At least the True 
Basic TIME function provided tenths of seconds or better reso- 
lution. Since we know that other languages are able to access the 
time in greater resolution, we may use the same function (ROM) 
to retrieve the time in greater resolution. This is especially 
important for benchmark tests where two compiled programs are 
being timed and the difference is tenths of seconds or better. In 
benchmarks that have been done in the past, sometimes the TIME 
function was used and there was rounding off to either O or 1 
second. A program running in 0 seconds is absurd, but that was 
the best we could do with MS Basic at the time. QuickBASIC 
and ZBasic both allow access to the TickCount call (Macintosh 
ROM). In QuickBASIC a typical benchmark might be imple- 
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Analog Alarm Clock 


AlarmTime: 09:55:00 12 
Current Time: 09:59:19 
Alarm is off 
9 3 
6 


Figure 1. The Time Machine 


mented such as: 
First initialize the ToolBox routine: 
TOOLBOX "I^ 


This must be used before any other ToolBox statement in the 
program. Now define a sub program or routine that can be called 
toreplace the other time functions usually used in the benchmark. 


SUB Tick (Count&) STATIC 

TrapNo$ = &HA975 

Count& = 0& : ‘Define the variable 
ToolBox "L^, TrapNo%, Count& 


END SUB 


Now call Tick(Count&) whenever you need the time. A tick 
is one-sixtieth of a second, enough for the tenth of a second 
accuracy provided by True BASIC's function. In ZBasic it is 
even easier to call TickCount. In ZBasic just use the function 
directly: 


Count&=FN TICKCOUNT 


AS you can see, accessing real time is really the simple part 
of the job. Accessing stored time is another aspect. I'll leave the 
subject of how the stored time became stored for later except to 
say that the Parameter RAM also stores the alarm setting. You 
can set the alarm with the Alarm Clock DA (included with your 
system software). 

The Analog Alarm Clock program included here demon- 
strates how you can retrieve the stored alarm time from the low- 
memory area. The Alarm time is stored at $200. The getAlarm 
routine retrieves the time by peeking at memory directly. The 
result is then converted to date information via the secs2date 


559 


toolbox routine. The Analog Clock program reveals some 
problems. The date conversion library routines are used to 
convert seconds to dates and dates to seconds. Secs2Date works 
fine, but there is a problem with the Date2Secs routine. This 
means that the Date2Secs routine must be called a different way. 
Fortunately, QuickBASIC provides the ToolBox call which 
allows you to make ROM calls yourself. The following lines 
replace the Date2Secs library routine: 


ToolBox “І” 


(Don’t forget to initialize the toolbox) 


ТгарМо%-%НА9СТ 
ToolBox *R^, TrapNo%, ReturnArrag&CO) МАЁРТЁСО {Кес (02) ) 
Al&=ReturnArrauk(2) 


It’s unfortunate that we have to go through that trouble, but 
that’s just the way it goes. I confess it took awhile before I 
realized that I wasn’t going to be able to get it to work without the 
ToolBox library call. 

In the program, alarm time is taken from parameter RAM 
and then it’s updated when changed when the alarm is turned on. 
Be careful when poking around the parameter RAM. If the 
wrong parameter gets changed you may have to Zap the parame- 
ter RAM to get started. You can do this by removing your 
MacPlus battery for a few minutes when your power is off or by 
holding down command-option when opening the control panel 
on newer Mac systems. 

Flashing the menu bar like the Alarm Clock DA does will be 
left for another day. Anybody know how to do that from Basic? 


What I' m not sure of is where the alarm status is stored. Happy 
New Year! 


‘Analog Alarm Clock Program 
701980 MacTutor 
‘by Dave Kelly 


DIM DtRec%(6), CenterRect%(3), pattern&(3) 
ToolBox "I" 

DIM ReturnArray& (5) 

GOSUB getAlarm 

false=0:true-NOT false 

PI=3. 14 159 


‘Set up menus 

MENU 1,0, 1, “File” 

MENU 1,1,1,"Turn Alarm On..^ 
MENU 1,2,0, ^-" 

MENU 1,3, 1, ^Quit^ 

CmdKey 1,3, Q^ 


‘ Get Screen size 
sheight-SYSTEMC6) 
swidth-SYSTEMC5) 
WINDOW !,"Analog Alarm Clock^,(4,44)-Cswidth-4,sheight-42,6 


‘Find the center of the window, centerx%,centery% 
‘ This should work with any size of screen 
wheight2-WINDOWC3) 

wwidthz-WINDOWC2) 

centerx$-wwidth2/2 

centery%=whe ight%/2 

circledia=centery%-25 
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GOSUB SetupClock 

ON MENU GOSUB MenuEvent 

ON DIALOG GOSUB DialogEvent 
DIALOG ON:MENU ON 


Loop: 

forecolor 33:’ change color to black 

t$=TIME$:’ Get the current time and separate into variables 
hour $=LEF T$¢¢ t$, 2) 

Min$-MID$Ct$, 4,2) 

Sec$-RIGHT$Ct$,2) 

H=VALChour$) : M=VALCMin$) : S=VAL(Sec$) 

IF H»12 THEN H=H- 12 

Н-Н%М/60 


“ Compute the angles for each hand of the clock 
SecAng le=(368-S*6 )*PI / 180 
MinAngle=(368-M*6 )*PI / 180 
HAng le=(368-H*38 )*P I / 180 


‘Draw the second hand 
CALL MOVETO (centerx%, centery%) 
ypointzCcircledia*COSCSecAngle22*.98 
xpoint=(circledia*%S INCSecAngle2)*.98 
CALL LINE (-xpoint,-ypoint) 
IF SecAngle<>01dSec THEN 
CALL MOVETO (centerx%, centery%) 
CALL PENMODE (11) 
ypoint-zCcircledia*C0OSCO1dSec2)*.98 
xpoint-zCcircledia*SINCOldSec22*.98 
CALL LINE (-xpoint, -ypoint) 
CALL PENMODE(8) 
END IF 


‘Draw the minute hand 

CALL PENSIZE(2,2) 

CALL MOVETO (centerx%, centery%) 

ypointzCcircledia*COS(MinAngle))*.9 

xpoint=(circledia*%SINCMinAngle))*.9 

CALL LINE (-xpoint,-ypoint) 

IF MinAngle<>01dMin THEN 
CALL MOVETO (centerx%, centery%) 
CALL PENMODE (11) 
ypoint=Ccircledia%®QSCOldMin))*.9 
xpoint-Ccircledia*SINCOldMin22*.9 
CALL LINE (-xpoint, -ypoint) 
CALL PENMODE(8) 

END IF 


‘Draw the hour hand 

CALL PENSIZE(4, 4) 

CALL MOVETO (centerx%, centery%) 

ypointsCcircledia/2*C0SCHAngle?) 

хроіпі=(сігс1едіа/2 INCHAngle2) 

CALL LINE (-xpoint, -ypoint) 

IF MinAngleo 01dMin THEN 
CALL MOVETO (centerx%, centery%) 
CALL PENMODE (11) 
ypoint-Ccircledia/23C08CO1dH2) 
xpoint2Ccircledia/2*8 INCO1dH2) 
CALL LINE (-xpoint,-upoint) 
CALL PENMODE(C8) 


END IF 
CALL PENSIZEC1, 1) 


forecolor 205:” Change color to red 
LOCATE 1,1:PRINT "AlermTime: *;AlarmTime$ 
forecolor 33:’ Change color to black 
LOCATE 2,1:PRINT "Current Time: *;t$ 
CALL TEXTMODECO) 
01dT$=t$ :01dSec=SecAngle:01dMin=MinAngle :01dH=HAngle 
CALL FILLOVALCVARPTR(CenterRect%(0)), VARPTRCpat tern$ C022) 
IF Alrm=false THEN 
forecolor 273 
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LOCATE 3, 1:PRINT “Alarm is off^:60TO Loop 
ND IF 


forecolor 341:’Change color to Green 
LOCATE 3, 1:PRINT “Alarm is on ” 
‘Sound the alarm if time is up! 
IF t$=AlarmTime$ THEN 
BEEP :BEEP : BEEP 
LOCATE 4,1:PRINT “Alarm event occurred” 
END IF 
GOTO Loop 
DIALOG OFF 


SetupClock:’ Set up the face of the clock 

. activewindow-N INDOWC?O) 

WINDOW OUTPUT 1 

CALL TEXTSIZEC 14) 

CALL MOVETOCcenterx%-8, centery%-circledia-4) PRINT 412»; 
CALL MOVETOCcenterx$-8, centery$*circledia*20) PRINT “ 6°; 
CALL MOVETOCcenterx$-circledia-20,centery$*7) PRINT 799: 
CALL MOVETOCcenterx$*circledia* 10, centery$*7) PRINT "3"; 
PSET (centerx%, centery8) 

forecolor 205: ” Change color to red 

CALL PENSIZE(2,2) 

CIRCLE (centerx%, centery%),circledia 

CALL PENSIZEC1, 1) 

SetRect CenterRect&(@), centerx%-5, centeryS- 

9, centerx%+5, centery%+5 

forecolor 33:’ Change color to black 

SetRect pattern%(0), &HFFFF, &HFFFF, &HFFFF , &HFFFF 

CALL FILLOVALCVARPTRCCenterRect$C2)), VARPTRCpatternz(02)) 
WINDOW OUTPUT activewindow 

RETURN 


DialogEvent: 
d-DIALOGC?) 
SELECT CASE d 
CASE 1 
IF DIALOGC 1221 THEN editwindow=true 
CASE 4 


GOTO Quit 
CASE 5 
IF DIALOG(5)=1 THEN GOSUB SetupClock 
CASE ELSE 
END SELECT 
RETURN 


MenuEvent: 

menunumber-MENUC? ) 

nenuitem-MENUC 1) 

MENU 

IF menunumber=1 THEN 
IF menuitem=1 THEN GOSUB SetAlarm 
IF menuitem=3 THEN Quit 

END IF 

RETURN 


SetAlarm:^ Set the alarm 
Alrm=NOT Alrm 
DoSet: 
IF Alrm THEN 
MENU 1, 1, 1, "Turn Alarm Off" 
WINDOW 2,"^,(50,50)-(250, 150),2 
LOCATE 2, 1:PRINT “Alarm Time: ” 
IF AlarmTime$-"" THEN AlarmT ime$=TIME$ 
EDIT FIELD 1,AlarmTime$, С 100, 17)-C 165,32), 1 
BUTTON 1, 1, ^0K^,C40,452-C170, 75), 1 
editwindow-false 
WHILE editwindow=false 
WEND 
AlarmT ime$=EDI T$C 1) 
ag="": j=] 
WHILE MIDéCAlarnTine$, i, 0 *:^ 
a$-a$ MIDéCAlarnTinef, i, 1) 
і=1+1 
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WEND 
Ahour=VAL Ca$) 
ч Ahour>24 OR Аһоиг‹@ THEN GOTO DoSet 
a z^ 
i-i*1 
WHILE MID$KAlarmTinef, i, 10 *:^ 
e$-e$ MID$CAlarmTime$, i, 1) 
i=i+l 
WEND 
Amin=VAL(a$) 
"4 Amin»59 OR Amin<® THEN GOTO DoSet 
аф-”” 
1=1+] 
WHILE i<=LENCAlarmT ime$) 
e$-e$ MID$CAlarmTime$, i, 1) 
i=i+1 
WEND 
Asec=VAL(a$) 
ч Asec)59 OR Авес<0 THEN GOTO DoSet 
а -У”” 
di 2. 10 THEN a$="0"+STRECAhour) ELSE a$=STR§CAhour ) 
8а%-аф”:” 
4 m 10 THEN а$=а$+^0"+8ТВ$САт1п) ELSE a$-e$*STRéCAmin) 
a$-e$*":"^ 
IF Аѕес‹ 10 THEN a$=a$+"0" +STRGCASec) ELSE a$=a$+STR$(Asec) 
AlarmT ime$=*" 
FOR 1=1 TO LENCa$) 
IF М10$ $, 1, 190% * THEN 
AlarmT ime$=AlarmT ime$- MIDQCa$, i, 1) 
NEXT i 
DtRec¥(3)=Ahour 
DtRec%¥(4)=Amin 
DtRec%(5)=Asec 
‘Call Date2secs routine (QuickBASIC Date2secs does not work 
right) 
ТгарМо%-%НА9СТ 
ToolBox “R”, TrapNo%, ReturnArrauk(@) VARPTR(DtRec%(0)) 
Alk=ReturnArrauk(2) 
POKEL &H200, A1& 
WINDOW CLOSE 2 


LSE 
TEXTMODE (25:LOCATE 2, 1:PRINT^ 


MENU 1,1,1,^Turn Alarm On..4 
END IF 
RETURN 


getAlarm:’ Retrieve 
А1%- PEEKL(&H200) 
2,” А1%,0(Кес%(0) 
at=” 
IF DtRec%(3)< 10 THEN a$=20"+STR$C(DtRec%(3)) ELSE 
a$-STRéCDtRec2(3)) 
а$=а$ӱ+^: * 
IF DtRec$(4)<10 THEN a$-e$*"0" *STRÉCDtRec$C45) ELSE 
ag=a$+S TRECD tRec%(4)) 
а$=а$+”:^ 
IF DtRec%(5)< 10 THEN a$=a$+20"+STR$C(DtRec%(5)) ELSE 
a$=a$+STR$(DtRec%(5)) 
AlarmTime$z^^ 
FOR i=1 TO LENCa$) 
IF MID$Ca$, i, 20” " THEN 
AlarmTime$-AlarmTime$MID$Co$, i, 1) 
NEXT i 
RETURN 


Quit: 
WINDOW CLOSE ! 
END 
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Exploring the ADB 

The Apple Desktop Bus (ADB) is a simple local-area 
network that connects low-speed input-only devices (for ex- 
ample: keyboard or mouse) to the operating system and Macin- 
tosh hardware. ADB is supported only on the Macintosh SE and 
Macintosh II (and future Macintosh computers). It should first 
be understood that the standard mouse and keyboard drivers 
automatically handle the ADB functions. 

Communication with the ADB is accomplished with six 
routines located in the 256K ROM. These routines are used only 
if you need to access bus devices directly or communicate with 
a special device. This being the case, you will probably never use 
them. The typical access to ADB devices is through the Toolbox 
Event Manager routines (ex: GetNextEvent or WaitNextEvent). 
In BASIC, the DIALOG statement handles this process. We 
have discussed the DIALOG statement in detail in previous 
volumes of MacTutor (see Jan, 1987;Aug, 1987; Sep, 1987). 

Macintosh Technical Note #206 is inspiration for this col- 
umn. #206 explains how ADB works on the SE and II. The 
question was asked, “How can I turn on/off the LEDs on the 
Apple Extended Keyboard?”. The answer: “Using the LEDs on 
the extended keyboard involves the ADBOp call (Inside Macin- 
tosh Volume 5 ). Once you determine that you have the extended 
keyboard, (with CountADBs, GetIndADB), then register 2 of the 
extended keyboard has the LED toggles in the low 3 bits. 
Therefore, you would do a talk to register 2 to have the device 
send you the contents of register 2, manipulate the low three bits 
to set the LEDs, and then pass the now modified register 2 back 
to the device with a listen to register 2 command." 

The first task is determining that the extended keyboard is 
being used. The SysEnvirons Function is another good way to 
determine if the extended keyboard exists although CountADBs 
and GetIndADB will have to be used to get the actual keyboard 
address. The extended keyboard will have an ID of 2anda device 
handler of 2. The standard apple keyboard will have an ID of 2 
and a device handler ID of 1. Several examples of SysEnvirons 
have been given in previous articles. The use of the SysEnvirons 
function in ZBasic is shown in the Basic example in this column. 


LS Pascal 2.0 Version 

In addition to the ZBasic example, the same program was 
coded in LS Pascal 2.0 and extensively modified by David Smith, 
Editor and Publisher of MacTutor. This Pascal example shows 
how the same information displayed in the ZBasic program can 
be displayed using Text Edit in a fully operational text edit 
window. Multifinder is supported with suspend/resume events, 
text selection, cutting and pasting is supported, the scrap is 
updated properly for Multifinder, and the use of two new 
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= Moin Window apa as 


Has Floating Point Coprocessor : Yes 
Has Color QuickDraw: Ves 
Type: Apple extended keyboard 


Working Directory Yolume Ref = -32717 


ada the keyboerd lights blink... 


Fig. 2 Same program in LS Pascal: MultiFinder 
Friendly Text Edit Window! 


resources, vers and mstr are used. The vers resources allow the 
version to be displayed in two places in the GetInfo box. The mstr 
resources allows MultiFinder to find the Quit command so the 
program can exit gracefully after a shutdown command. Both 
programs parse and display the SysEnvirons information about 
the Mac and then blink the keyboard lights if an extended 
keyboard is present. 


ZBASIC 5.0 Version 

To use SysEnvirons in ZBASIC 5.0 you will first need to 
modify the function using the Toolbox editor program. The 
SysEnvirons function is register based and so the function is 
modified to reflect this. When I tried the SysEnvirons function 
included in ZBASIC 5.0, the function did not return the correct 
results. Change the function to: DO. WZFN SYSENVIRONS 
(DO.L, AO.L) This sets the result to register DO with inputs 
passed to the function in the DO and AO registers as shown in 
Inside Macintosh Vol. V, pg. 6. An explanation of the SysEnvi- 
rons record is given on pg. 6-8. The source code disk for this 
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month includes the ADB ZBasic 5.0 library which the Toolbox 
editor program can move into ZBasic to create a new version of 
ZBasic with the correct calling sequence for Sysenvirons. The 
ability to extend the language to new traps or correct old ones is 
a very clever ability in ZBasic 5.0. It means you don't have to get 
a new version of the program when the toolbox calling routines 
or traps change. 


Accessing an ADB Device 

There are 16 possible device locations available on the ADB. 
Each device can maintain up to four variable-size registers which 
may be read or written from the device over the ADB network. 
All devices use register 0 and register 3. Register 0 is used to store 
input data for device interrupts. Register 3 is used for device 
identification and operating flags. The chapter on the ADB 
Manager in Inside Macintosh Vol. V explains these two registers 
in more detail for writing device drivers. The other two registers 
may or may not be used depending upon which device is being 
used. The Extended Keyboard uses register 2 as indicated by the 
comments in TN#206. 

Devices which connect to the ADB contain their own micro- 
processors, which handle both device routines and the ADB 
interface. Sending commands to the device is accomplished with 
the ADBOp function. There are four possible commands which 
may be sent to the device. The ADB Command Formats are 


; IKE 


PN 


TO): с 


. 000а 20а 0n dOa d0 
00m dün dln 00m 30m 
Әбафбадйад0адбад 
B608 Падбад0йадбадбад0 


Е 


а 


. 4 Register 2 = 02ҒҒҒ8 before listen command 


shown on pg. 363 of Inside Macintosh. A description of the 
commands is given on page 364. We use the Talk command to 
tell the device that we want to see register 2 by sending a 
command of $2E (binary ‘0010 1110’). The buffer pointed to by 
the ADBOpBlock parameter block will contain the contents of 
register 2 after the ADBOp function is called. As seen in the 
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LightsBug window the contents of the buffer after the Talk 
command is sent is O2FFFF. Since the technical note states that 
the LEDs are toggled on/off in the lower three bits, changing the 
contents of the buffer to 02FFF8 and sending the Listen com- 
mand should turn on all three lights. The first byte of the buffer 
($02) is the number of bytes in the buffer. (See figures 3 & 4) 


The Listen command is used to write the register back to the 


device. When the Listen command is sent after modifying the 
lower 3 bytes of register 2 (as stored in the buffer area), the LEDs 
do in fact turn on. The reverse process may be used to turn off the 
LEDs or sending the Flush command also clears the LED status. 


The ADBOpBlock record (referred to by the ADBOp func- 


tion) contains a pointer to the buffer where the registers are stored 
(as discussed above) and a pointer to a completion routine and 
data pointer. The completion routine is called by ADBOp upon 
completion of the function. There are three ways that a comple- 
tion routine may be used. 1) You may pass a nil pointer to 
ADBOp when you do not wish to have a completion routine. 2) 
You may use the service routine address which is fetched by the 
GetIndADB function or GetADBInfo function. Before calling 
ADBOp, set the completion pointer to the service address. 3) 
Use your own completion routine. The data pointer is an area 
which the completion routine may use (optionally) to store its 
own data. 


There is rarely a reason to call ADBOp except to tell the 


device something or turn on LEDs as in this example. In most 
cases, the ADB device communication will be handled by the 
system's internal polling/service request mechanism. 


Thetwo program examples included here, one in ZBasic 5.0, 


the other in LS Pascal 2.0, illustrate this process. The flow of the 
program is much easier to follow in Pascal because of the 
organization of the record structures. The result is the same. In 
order to get ZBasic to recognize the ADB Manager routines, they 
must be added using the Toolbox Editor. The definitions of the 
functions and procedures which must be added are shown below 
(these are included in a library file on this month's source code 
disk): 


In the Pascal version, a complete Macintosh text edit appli- 


cation is given. À menu function, ADB, in the File menu, causes 
the doADB procedure to be called from the procedure which 
handles a mouse down event. When the doADB proc executes, 
itparses the SysEnvirons call and inserts the same information as 


Mac Functions File:"RDBs Library" 
(Trap-R0?8) 00.Ш-ҒМ GETINDRDB (RO.L,DO.L) 
(Trap=R077) DO.W=FN COUNTRDBS 
(Trap=R079) DO.W=FN GETRDBINFO (RO.L,DO.L) 
(Trap-RO?R) DO.W=FN SETRDBINFO (RO.L,DO.L) 
(Trap-R0?C) 00.Ш-ҒМ RDBOP (RO.L,DO.L) 
(Trap-R090) DO.W=FN SYSENUIRONS (DO.L,RO.L) 


Mac Procedures File:"RDBs Library" 
(Trap=R07B) CRLL RDBREINIT 


Fig. 5 ZBasic SysEnvirons and ADB Functions 
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the Basic program into the text edit record for the program's 
window. That information is then displayed as the result of an 
update event. This is how you would duplicate the functionality 
of Basic’s print statements using a text edit record in a Pascal 
program that entirely uses the Macintosh toolbox for output into 
a window. Pay particular attention to the resource file at the end 
of the program. There in RMaker format, is the two new re- 
sources for inserting a version in the GetInfo dialog box, and for 
helping MultiFinder quit your application. Note also that the 
SIZE resource has the necessary information to tell MultiFinder 
that our application understands a suspend/resume event. This 
event, number 15, is treated much like an activate/deactivate 
event. By allowing for event 15, we save MultiFinder from 
sending us a lot of activate/deactivate events we don’t need, 
thereby making the quasi-multi-tasking scheme work better. 
These two new resources are described in a recent tech note #189. 

The other significant feature of the Pascal program is that it 
correctly allows the window to be re-sized. This requires a proper 
Update Event procedure and a Grow procedure. The key is that 
the rectangles for the text edit viewing rectangle, the scroll bars 
and the grow box all must be defined properly. Controls are 
active and updated properly, but no value was assigned the 
control, so it doesn’t indicate scrolling even if the window is 
made small enough to cover some of the text. A scrolling unit is 
needed to match the control to the number of lines of text and the 
insertion point. For an example of how to do this, see the Text 
Edit example by David Smith from last year’s MacTutor volume 
3. That program had a working multiple window example of text 
edit with scrollers. 

For more information refer to the ADB Manager chapter of 
Inside Macintosh and technical notes on ADB. 


Environment Version = 1 
Machine Type = Macintosh 11 


Frocessoer = DM nettle i [reme 
Has Floating Point Coprocessor (12Y) = 1 
Нез Color QuickDrew (1=Y) = 1 


Keyboard Type = Apple extended keyboard 
Appletelk Driver Version = 49 
Working Directory Volume Ref = - 52717 


Watch the keyboard lights blink... 


Fig. 6 Our Pascal Demo supports Text Editing 


‘ SysEnvirons and ADB Demo 
7 01989 MacTutor 

' by Dave Kelly 

' ZBasic 5.0 

f 


OXXXXXXXXXXEXXEEOEGEXOOEEXXXXXXEXEXXXXEXXXXxXx*xrzrExEirxztxxzxxxxxxxk 


‘ First check the System Environments 
‘ To do this the SYSENVIRONS function needs to be 
* modified to work. Replace old SYSENVIRONS with D0.W=FN 
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“ SYSENVIRONSCDO.L, Аб.) 
(XXFXFXXXXX7XXXFXXX5XXXXXXXXXXX7XXXXX5SXXXXXXXXXX417X1FXXXFEXXXEX 
WINDOW OFF 

COORDINATE WINDOW 

‘Find out screen size. 

CALL GETWMGRPORT CiMgrPor th > 

PortTop=PEEK WORDCWMgrPor t&+8 ) 

PortLeft=PEEK WORDCWMgrPort&* 10) 

Por tBottom=PEEK WORDCWMgrPor t&+ 12) 

Por tRight=PEEK WORDCWMgrPor t&+ 14) 


WINDOW 1,“Main Window’, (18, 44)-CPortRight-4,PortBottom-4), 1 
‘Bring window to the front (necessary under Multif inder ) 
Wo tr&=WINDOWC 14) 
CALL SELECTWINDOWCWptr&) 
б Set up SysEnvRec 
DIM environsVersion, machineType, 
sys temversion, processor ,hasFPU, keyBoardType , &t0r vr VersNun, sysVRef Num 
OSErr$=FN SYSENVIRONSC 1, VARPTRCenvironsVersion)) 
LONG IF OSErr$=0 
PRINT “Environment Version: *;environsVersion 
PRINT “Machine Type: ^; 
SELECT machineType 
CASE @ 
PRINT “new version of Macintosh” 
CASE 1 
PRINT “Macintosh 512K enhanced” 


PRINT “Macintosh Plus” 
PRINT “Macintosh SE” 


PRINT “Macintosh II^ 
CASE -1 
PRINT “Macintosh with 64K ROM” 
CASE -2 
PRINT “Macintosh XL” 
END SELECT 
PRINT “System 
Version: ”;LEFT$CHEX$(systemversion),2);”.”;RIGHT§CHEX$(systemversion),2) 
PRINT “Processor : ^; 
SELECT processor 
CASE 0 
PRINT “new processor” 
CASE 1 
PRINT “MC68000 processor’ 
CASE 2 
PRINT “МС68010 processor” 
CASE 3 
PRINT “МС68020 processor” 
END SELECT 
b$="8X"+RIGHT$CBIN§ChasFPU), 8) 
hesColorQDsVALCb$) 
b$="&X"+LEFT§CBIN§ChasFPU), 8) 
hasFPU=VAL (b$ ) 
PRINT “Has Floating Point Coprocessor : ”; 
IF hasFPU=1 THEN PRINT “Yes? ELSE PRINT “No” 
PRINT “Has Color QuickDraw:”; 
IF hasColorQD=1 THEN PRINT “Yes? ELSE PRINT “No” 
PRINT “Keyboard Type:”; 
SELECT keyBoardType 
CASE 0 
PRINT “Macintosh Plus keyboard with keypad” 
CASE 1 
PRINT “Macintosh keyboard” 
CASE 2 
PRINT “Macintosh keyboard and keypad” 
CASE 3 
PRINT “Macintosh Plus keyboard” 
CASE 4 
PRINT “Apple extended keyboard” 
CASE 5 
PRINT “standard Apple Desktop Bus keyboard” 
CASE ELSE 
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PRINT “don't recognize this one!” 


END SELECT *Togglelightsoff ^ 
PRINT “AppleTalk Driver version: ^;atDrvrVersNum О5ЕггЖ-ҒМ ADBOPCVARPTRCbuf ferptr&),F lush$) 
PRINT "Working Directory Volume Reference *:”;sysVRefNum RETURN 

XELSE 
PRINT “Error -”:05Егг% “Delay” 

END IF T1&=FN TICKCOUNT 

КККК КККК 00 

"^ Now Read the ADB T&=FN TICKCOUNT 

‘ This routine turns on and off the UNTIL T&-T1&-20 

‘ lights of the Extended keyboard RETURN 


^ ADB calls and functions need to be added to ZBasic 5.0 


‘ using the Toolbox mover program. 
'ЖЖЖЖЖЖАЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖ 
f 


IF keyBoardType<>4 THEN END 

DIM DeviceType%, ServiceAddress&, DataAddress&:’ GETINDADB 
Parmeter block 

DIM buffer% (2) 

bufferptr&zVARPTRCbuffer2C02) 

compRoutptr&-0 

Datablkptr&-0' ADBOP Parameter block 


RDB Demo 


Queries System, blinks lights 
RDB Demo 
O by Dave Kelly & Dave Smith 


ver 2 MAR 1989 
= K 
numberof ADBdevices=FN COUNTADBS Memory = 104544 | р | 
PRINT “There аге“; питрегоѓА0Ваеуісеѕ; “ADB devices present." 
IF numberof ADBdevices=@ THEN STOP 
FOR 1%-1 TO numberof ADBdevices Fig. 7 Our Pascal About Box. Note Memory Function 


ADBAdd&=FN GETINDADBCVARPTR(DeviceTypeS), i$) and ID String displayed from resources! 
b$=“&X"”+RIGHT$CBIN$(DeviceTypeS), 8) 


Or gADBAddress%=VAL (b$) 


b$="&X"+LEF T$(BIN$(DeviceTypeS), 8) ( ADBDemo } 
DeviceType%=VAL (0%) ( ©1989 MacTutor) 
LONG IF ADBAdd%=2 ‘Got the address for the Extended ( By Dave Kelly, modified by David Smith) 

Keyboard ( This program will blink the LEDs of the Extended Keyboard on 
Talk®=&H2E:’ Talk command and off twice. This has no real value other than to show how 
Listen%=&H2A:’ Listen command to communication with ADB devices. NOTE: It is not clear what 
Flush$-&H21:^ Flush command Apple has in mind for these LEDs, so you are using them at 

PRINT "Press any key to continue..." your own risk. Refer to Technical Note 8206 for more informa- 
DO tion. Other tidbits include Multifinder friendly, about 
X$- INKEY$ dialog, vers resources, working sizable window. ) 
GOSUB "MagicL ights" 
UNTIL хф ^^ program ADBDemo; 
END IF 
NEXT i$ uses 
LONG IF Х$=*^*^ OSIntf, PrintTraps, MyADBGlobals, MyADBStuff ; 
PRINT "Press any key to continue..." 
DO procedure crash; 
X$- INKEY$ begin 
UNTIL x$o ^" ExitToShe11; 
END IF end; 
END 
procedure InitMac; 

^MagicL ights^ begin 

00508 *Togglelightson" InitGraf CéthePort); 
GOSUB “Delay” InitFonts; 

GOSUB “Togglelightsoff” InitWindows; 
00508 “Delay” Ini tMenus; 
60508 "Togglelightson"^ TEInit; 
GOSUB “Delay” InitDialogs(@crash); 

GOSUB *Togglelightsoff" InitCursor ; 

GOSUB “Delay” FlushEventsCeveryEvent, 0); 
RETURN Finished := false; 
end; 

“Togglel ightson” 

compRoutptr&=ServiceAddress& :Datab lkptr&=DataAddress& procedure initRects; 

‘This call reads register 2 of the ext. keyboard. var 

OSErr%=FN ADBOPCVARPTRCbuf ferptr&), Talk%) MemoryPtr: “Integer; 

GOSUB “Delay” begin 

buf Ғег%( 1)=&HF800 MemorgPtr :- pointer(mBarHeightGlobal); 

‘The next call writes register 2 back to mBarHeight := MemorygPtr^; 

‘the extended keyboard. For some reason the register is not screen := ScreenBits.Bounds; (current screen device} 

‘being written back to the keyboard. See Pascal version. SetRect(DragArea, Screen. left + 4, Screen.top + mBarHeight + 

OSErr%=FN ADBOPCVARPTR(buf ferptr&),Listen%) 4, Screen.right - 4, Screen.bottom - 4); 

RETURN SetRect(GrowArea, Screen. left + MinWidth, Screen. top + 
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MinHeight, Screen.right - 8, Screen.bottom - 8); DisableI temCmyMenus[EditM], eUndo); 


SetRectCADBWindowRect, Screen.left + 15, Screen.top + 45, DrawMenuBar ; 
Screen.right - 95, Screen.bottom - 95); end; (of proc} 
SetRect(ZoomRect, Screen. left + 4, Screen.top + mBarHeight + 
4, Screen.right - 4, Screen.bottom - 4); procedure doMouse (myEvent: EventRecord); 
end; var 
whereIsIt: integer; 
procedure InitMyWindow; whichWindow: WindowPtr; 
var localPt, globalPt: Point; 
windtype: integer; oldPort: GrafPtr; 
Visible: boolean; begin 
GoAway: boolean; globalPt := myEvent .where; 
RefVal: LongInt; localPt := globalPt; (global coord of mouse) 
title: str255; GlobalToLocalClocalPt); (local coord of mouse) 
begin wherelsIt := FindWindow(globalPt, whichWindow); 
Visible := true; case whereIsIt of 
windtype := documentProc + ZoomBox; inDesk: (0) 
GoAway := true; doMessage( ‘Mouse Click on Desktop.’, ‘CNot handled in 
RefVal := 0; this program.)’, '', ''5; 
title := “ADB Demo’; inMenuBar: (1) 
ADBWindow := NewWindow(nil, ADBWindowRect, title, Visible, doMenuBar (MenuSelect(CglobalPt)2; 
windtype, pointer(-1), GoAway, RefVal); inSysWindow: (2) 
ADBWindowPeek := WindowPeekCADBWindow); SystemClick(myEvent, whichWindow); 
SetPor t CADBW indow2; inContent : (3 
TextFont (Geneva); doContent(myEvent, whichWindow); 
TextSizeC 10); inDrag: (4) 
TextFaceCL 12; (plain) doDrag(whichWindow, globalPt); 
TextMode(1); (Or) inGrow: (5) 
PenNormal; doGrow(whichWindow, globalPt, False); 
ForeColor(blackColor); inGoAway: (6) 
BackColor(whiteColor); 1f TrackGoAwau(whichWindow, globalPt) then 
ADBWindowPeek*.windowKind := userKind; HideWindow(whichWindow); 
with ADBWindow^ .portRect do inZoomIn, InZoomOut: (7, 8) 
begin begin 
SetRect(VCRect, right - (SBarWidth - 1), top - 1, right if TrackBox(whichWindow, globalPt, whereIsIt?) then 
+ 1, bottom - (SBarWidth - 22); begin 
SetRect(HCRect, left - 1, bottom - (SBarWidth - 1), GetPortCOldPort); 
right - (SBarWidth - 2), bottom + 1); SetPort(whichWindow); (safety device) 
SetRect(GrowRect, HCRect.right, HCRect.top, EraseRect(whichWindow^ .portRect); 
VCRect.right, HCRect.bottom); ZoomWindow(whichWindow, whereIsIt, True); 
SetRect(ViewRect, left + 4, top + 4, right - (SBarWidth doGrowC(whichWindow, globalPt, True); 
- 1), bottom - (SBarWidth - 125; SetPort(0ldPort); 
end; (of with ) end; 
DestRect := ViewRect; end; 
myTextHandle := TENew(DestRect, ViewRect); otherwise 
title := “2; begin 
VControl := NewControlCADBWindow, VCRect, title, Visible, end; 
0, 0, 0, ScrollBarProc, 1); end; (of wherelsIt) 
ValidRect(VCRect); end; 
HControl := NewControlCADBWindow, HCRect, title, Visible, 
0, 6, 0, ScrollBarProc, 1); procedure doKeuDowns (muEvent: EventRecord); 
ValidRect(HCRect); var 
end; ch: char; 
charCode: longInt; 
procedure InitMyPr int; keyCode: longInt; 
begin begin 
myPrint := THPrintCNewHandleCSIZEOFCTPrint))); charCode := BitAnd(myEvent.Message, charCodeMask); (strip 
end; off key code} 
keyCode := BitShift(BitAnd(myEvent.Message, keyCodeMask), 
procedure InitMyMenus; -8); (strip off char} 
var ch := Chr(charCode); (get keyboard char) 
i: integer; 1f BitAnd(myEvent Modifiers, CmdKey) = CmdKey then 
begin doMenuBar(MenuKeyCch2) ( do menu command key} 
myMenus [AppleM] := GetMenuCAppleMenu?; else 
AddResMenu(myMenus[AppleM], 'DRVR'); begin ( do keystroke ) 
myMenus [FileM] := GetMenu(FileMenu); ParamText( “Мо typing supported..’, ‘’, “, 49; 
myMenus[EditM] := GetMenuCEdi Меги); itemhit := CautionAlert(AlertDialog, nil); 
for i := 1 to MenuCount do end; (of do key stroke ) 
InsertMenuC(myMenusli], 0); end; (of proc) 
DisableI temCmyMenus[FileM], fSave); procedure doUpdates (myEvent: EventRecord); 
DisableItem(myMenus[F ileM], fSaveAs); var 
DisableItem(myMenus[FileM], fPageSet); UpdateWindow: WindowPtr ; 
DisableItemCmyMenus(FileM], fPrint); TempPort: GrafPtr; 
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muRect: rect; 
begin 
UpdateWindow := WindowPtr(muEvent.message); 
1f UpdateWindow = ADBWindow then 
begin 
GetPort(TempPort); (save port) 
SetPortCUpdateWindow); 
BeginUpDateCUpdateWindow); 
EraseRect UpdateWindow^ .portRect); 
DrewGrowIconC(UpdateWindow); 
DrawControlsC(UpdateWindow); 


TEUpdateCUpdateWindow^.portRect, myTextHandle); 


EndUpDateCUpdateWindow); 
SetPortCTempPort); (restore port) 
end; 
end; (of proc) 


procedure doActivates (myEvent: EventRecord); 


var 

TergetWindow: WindowPtr; 

TergetPeek: WindowPeek; 

begin 

TargetWindow := WindowPtr(myEvent message); 
TergetPeek := windowPeek(TargetWindow); 
SetPortCTargetWindow); 
1f Odd(myEvent modifiers) then 

begin (activate) 

if TargetWindow = ADBWindow then 
begin 


DisableI tem(myMenus[EditM], eUndo); 


DrawGrowIcon(Targe tW indow): 
TEActivate(myTextHandle); 
ShowControlCVControl); 
ShowControl(HContro1); 
end 
end ( of activate loop) 
else 
begin (deactivate) 
1f TargetWindow = ADBWindow then 
begin 
Enableltem(muMenus[EditM], eUndo); 
Enableltem(muMenus[EditM], eCut); 
Enableltem(muMenus[EditM], eCopu); 


Enableltem(muMenus[EditM]), ePaste); 
Enableltem(muMenus[EditM], eClear); 


DrawGrowlcon(TargetWindow); 
TEDeactivate(mulextHandle); 
HideControl(VContro1); 
HideControl(HContro1); 
end; ( of my window activation) 
end; (of deactivate loop} 
end; (of proc) 


procedure doMulti (myEvent: EventRecord); 
const 
MouseMovedEvt = $FA; 
var 
HiByte: byte; 
bit®: LongInt; 
sysresult: boolean; 
ResumeWindow: WindowPtr; 
ResumePeek: WindowPeek ; 
SuspendWindow: WindowPtr; 
SuspendPeek: WindowPeek; 
MouseMove: LongAndByte; 
begin 
bitð : ; {convert 68000 to toolbox) 
(check (у AER moved event) 
MouseMove. longView := myEvent.message; 
HiByte := ByteCMouseMove.byteView.byted); 
1f HiByte = MouseMovedEvt then 
begin (Handle mouse moved event} 
end; 
(check for resume event ) 
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if Odd(myEvent.message) then 
begin (resume) 


treat like activate Event if we are in front) 


ResumeWindow :- FrontWindow; 
1f ResumeWindow - ADBW indow then 
begin (adbWindow) 
SetPortC(ResumeW indow); 
InvalRect (ResumeW indow^ .portRect); 
{ force update event) 
DisableI tem(myMenus[EditM], eUndo); 
ShowControlCVContro1); 
ShowContro!CHContro1); 
DrawGrowIcon(ResumeW indow); 
end; (adbWindow) 
1f FrontWindow © nil then 
begin (DA check} 
ResumePeek : = WindowPeek(FrontWindow); 


if ResunePeek^ .windowK ind < Ø then (DA) 


begin (da) 
myEvent.what := activateEvt; 
BitSetC@myEvent. modifiers, 51409; 
susresult := SustemEvent(muEvent); 
end; (da) 
end; (DA check) 
( end of activate Event) 
end (of resume) 
else 
begin (suspend) 
de-activate Event) 
SuspendWindow := FrontWindow; 
1f SuspendWindow = ADBWindow then 
begin (adbwindow) 
SetPort(SuspendWindow); 
InvalRect(SuspendWindow" .portRect); 
(force update) 
Enableltem(muMenus[EditM], eUndo); 
Enableltem(muMenus[EditM] eCut); 
Enableltem(muMenus[EditM], eCopu); 
Enableltem(muMenus[EditM], ePaste); 
Enableltem(muMenus[EditM] eClear); 
DrawGrowIcon(SuspendWindow); 
HideControl(VControl); 
HideControl(HControl); 
end; (adbwindow) 
1f FrontWindow © nil then 
begin (DA check) 
SuspendPeek :- WindowPeek(FrontWindow); 
1f SuspendPeek* .windowKind < 0 then 
begin (da) 
myEvent.what := activateEvt; 
BitClrCenyEvent. modif iers, bit0); 
sysresult := SustemEvent(muEvent); 
end; (da) 
end; (DA check} 
( end of de-activate Event) 
end; (suspend) 
end; (of proc) 


procedure MainEventLoop; 
const 
MultiFinderEvt = 15; 
var 
sleep: LongInt; 
Event: EventRecord; 
DoIt: Boolean; 


begin 
Sleep := 10; 
repeat 
= die Murex thandie), 


Dolt : = WaitNextEvent(EveruEvent, Event, sleep, nil); 
(no mouse tracking) 


1f DoIt then 
case Event.what of 
mouseDown: 
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doMouse(Event); 
KeuDown, Autokeu: 
doKeuDowns(Event); 
updateEvt: 
doUpdates(Event); 
activateEvt: 
doActivates(Event); 
MultiFinderEvt: 
doMulti(Event); 
otherwise 
begin 
end; 
end; (of event case) 
until Finished; (end program) 
end; 


begin ( main ) 
InitMac; 
InitRects; 
InitMyWindow; 
InitMyPrint; 
InitMyMenus; 
MainEventLoop; 

end. ( end of mein ) 


unit MyADBStuf f ; 
interface 


uses 
OSIntf, PrintTraps, MyADBGlobals; 


procedure doMessage (messageð: str255; messagel: str255; 
message2: str255; message3: str255); 

procedure doAbout; 

procedure doQuit; 

procedure doMenubar (menuResult: LongInt); 

procedure doContent (ConEvent: EventRecord; contentWindow: 
windowP tr); 

procedure doDrag (GrabWindow: WindowPtr; GlobalMouse: 
point2; 

procedure doGrow (ResizeWindow: WindowPtr; Globalmouse: 
point; Zoomflg: Boolean); 


implementation 


procedure Шш ((пез5адей : str255) 
message! : str255) 
(message2 : str255) 
(message3 : str255)} 
var 
dialogP: DialogPtr; 
item: integer; 


gin 
ParamText(message®, messagel, message2, message3); 
dialogP := GetNewDialog(MessageDialog, nil, pointer(-1)); 
1f dialogP = nil then 
begin 
SysBeep(5); 
ExitToShe11; 
end; 
initCursor; (change to arrow) 
ModalDialog(nil, item); 
DisposDialog(dialogP); 
end; 


procedure delay; 
const 
stalltime = 15; (quarter seconds in ticks) 
var 
i: LongInt; 
tick1, tick2: LongInt; 
begin 
tick1 := TickCount; 
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tick2 := tick]; 
repeat 
tick2 := TickCount; 
until tick2 >= ticki + stalltime; 


end; 
procedure togglelightsoff; 
const 
f lushcommandNum = $21; ( 00100001 ) 
begin 


Buf .opServiceRtPtr := Info.dbServiceRtPtr; 
(service routine pointer) 
Buf .opDataAreaPtr := Info.dbDateAreeAddr; 
(optional data area address) 
OSEr := ADBOp(nil, nil, Buf.dataBuffPtr, flushcommandNum); 
( Flush command, clears the device ) 
1f OSEr = -1 then 
doMessage( ‘Unable to flush device’, '', °’, 4%); 
end; 


procedure togglelightson; 
var 
LEDaddress: ptr; 
LEDbyte: signedbyte; 
const 
talkcommandNum = $2E; ( 00101010 ) 
listencommandNum = $2А; ( 00101110 ) 
begin 
if OSEr = noErr then 
begin 
Buf .opServiceRtPtr := Info.dbServiceRtPtr ; 
(service routine pointer) 
Buf .opDataAreaPtr := Info.dbDateAreeAddr; 
{optional data area address) 
togglelightsoff ; 
OSEr := ADBOp(Buf .opDataAreaPtr, Buf .opServiceRtPtr, 
Buf .dataBuffPtr, talkcommandNum ); 
if OSEr = -1 then 
begin 
doMessage(‘Unable to talk to device’, ‘’, “°, 
у 
exit(togglelightson); 
end; 
delau; 
LEDaddress :- POINTERCORD(Buf .dataBuffPtr) + 2); 
LEDbyte := LEDaddress ; 
if LEDbute = -1 then 
LEDaddress^ := -8; (turn on) 
OSEr := ADBOp(Buf .opDateAreaPtr, Buf .opServiceRtPtr, 
Buf .dataBuffPtr, listencommandNum); 
if OSEr = -1 then 
begin | 
doMessage( ‘Unable to listen to device’, °’, 7”, 
ar 
exit(togglelightson); 


end; 
end; (of noErr) 
end; 


procedure LightsMagic; 

begin 
togglelightson; 
de lay; 
togglelightsoff ; 
delay; 
togglelightson; 
delay; 
togglelightsoff ; 
delay; 
togglelightson; 
delay; 
togglelightsoff ; 
delay; 
togglelightson; 
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delau; 


togglelightsoff; 
de lay; 
end; 
procedure QuerySystem; 
var 
stri, str2: str255; 
begin 


NunToString(LongIntCtheWorld.environsVersion), str2); 

strl := concat('Environment Version = ', str2, chr C132); 

TEInsert(pointerCord4Céstr 1) + 1), Length(str 1), 
MyTextHandle); 


case theWorld.machineType of 
0: 


str2 := “new version of Macintosh’; 
1: 
str2 := ‘Macintosh 512K enhanced’; 
2: 
Str2 := ‘Macintosh Plus’; 
3: 
Str2 := ‘Macintosh SE’; 
4: 
5472 := ‘Macintosh II’; 
otherwise 
begin 
if theWorld.machineType = -1 then 
Str2 :- ‘Macintosh with 64K ROM’; 


1f theWorld.machineType = -2 then 
str2 := ‘Macintosh XL’; 
end; 
end; (of case) 
stri := concat('Machine Type = ', str2, chr(13)); 
TEInsert(pointerCord4C8str1) + 1), Length(str 1), 
MygTextHandle); 


NumToStringC(LongInt(CtheWorld.systemVersion), str2); 

бігі := concat( ‘System Version (must convert to hex) = 
str2, chr 132); 

TEInsert(pointerCord4C8str 1) + 1), Length(str 1), 
MyTextHandle); 


case theWorld.processor of 
g ' 


“str2 ‚= ‘new processor’; 
J: 

str2 :- 'MC68000 processor’ ; 
2: 

str2 := “MC68010 processor’; 
3: 

Str2 := 'MC68020 processor’; 
4: 

6іг2 :- “MC68030 processor’; 
otherwise 

begin 

Str2 := ‘unknown processor’; 
end; 


end; (of case} 

stri := concat( ‘Processor = ', str2, chr(13)); 

TEInsert(pointerCord4C8str1) + 1), Length(str 1), 
MyTextHandle); 


NumToStr ing(LongIntCtheWor ld. hasFPU), str2); 

stri := concatC'Has Floating Point Coprocessor (1=Y) = 
str2, chr(13)); 

TE Inser t(pointerCord4(éstr1) + D, Length(str 1), 
MyTextHandle); 


NumToStr ing(LongInt(theWor1d.hasColorQD), str2); 

stri := concat('Has Color QuickDraw (1=Y) = ', str2, 
chr( 132); 

TEInsert(pointerCord4C8str 1) + 1), Length(str DD, 
MyTextHandle); 
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f 


д 


case theWorld.KeuBoardTupe о? 


0: 

str2 := ‘Macintosh Plus keyboard with keypad’; 
1: 

str2 := ‘Macintosh keyboard’; 
2: 

Str2 := ‘Macintosh keyboard and keypad’; 
3: 

str2 := ‘Macintosh Plus keyboard’; 
4: 

str2 := ‘Apple extended keyboard’; 
5: 

Str2 := ‘Standard Apple Desktop Bus keyboard’; 
otherwise 

begin 

Str2 := ‘Unknown keyboard value’; 
end; 


end; {of case) 

stri := concat('Keyboard Type = ”, str2, chrC 1325; 

TEInsert(pointerCord4Céstr 1) + 1), Length(str 1D, 
MyTextHandle); 


NunToStr ingCLongIntCtheWor 1d. atDrvrVersNum), str2); 

strl := concat('Appletalk Driver Version = 2 str2. 
chr( 132); 

TEInsert(pointerCord4(@str 1) + 1), Length(str 1), 
MyTextHandle); 


NumToStr ingCLongInt( theWorld.sysVRefNum), str2); 
5471 := concat( ‘Working Directory Volume Ref = 
chr( 1322; 
TEInsert(po inter Cord4C&str 1) + 1), Length(str 1), 
MyTextHandle); 
end; 


A str2, 


procedure doADB; 
var 
devTableIndex: 
бігі: str255; 
begin 
TESetSelect(®, TEMax, MyTextHandle); 
TEDeleteCMyTextHandle); 
ShowWindowCADBW indow); 


integer; 


OSEr := SysEnvirons(versRequested, theWorld); 
if OSEr = envNotPresent then 
doMessage('System File older than 4.1!^, 7”, 
if 05Ег = envBadVers then 
doMessage( ‘Bad Version Requested’, 
if OSEr = envVersTooBig then 
doMessage( ‘Requested Version Not Available’, ‘’, '' 


, 2 


77 f^. 
$9 


7 f (^N. 
4 ) ); 


ER 
if OSEr = noErr then 
begin (Query and Blinking routine} 


QueruSustem; 


{toggle keyboard lights on and off) 
if theWorld.keuBoardTupe = 4 then 
begin (keyboard type 4} 
бігі :- concat(chr( 13), 
е chrC132); 
TEInsert(po interCord4C8str 1) + 1), Length(str 1) 


‘Watch the keyboard 
lights blink.. 


MyTextHandle); 


numberofADBs := CountADBs; 
for devlableIndex := 1 to numberofADBs do 
begin (devTable Index} 
ADBAddr := GetIndADBCinfo, devTableIndex); 
( find the device address } 
1f ADBAddr = 2 then 
begin (ADBAddr) 
device := info.devType; 


LightsMagic; 
end; (of ADBAddr) 
end; (devTableIndex) 
end; (keybaord type 4) 
end; ( of noErr) 
end; (of Proc) 


procedure doAbout; 
var 
IDStrHandle: StringHandle; 
dialogP: DialogPtr; 
item: integer; 
Stri, Str2, Str3: str255; 
myHeapSpace: LongInt; 
FreeSpace: Size; 
begin 
IDStrHandle := StringHandle(GetResource(rsrc, 02); 
1f IDStrHandle = nil then 
begin | 
doMessage( ‘Get About box crash!’, °’, “”, '^); 
ExitToShell; 


end; 
MoveHHiCHandleCIDStrHandle2); 
HLockCHandleCIDStrHandle)); 
FreeSpace := FreeMem; 
myHeapSpace := MexMem(FreeSpace); 
NumToString(myHeapSpace, Str2); 


Str2 := concatC'Memory = ', Str2); 
Str3 := '^; 
Stri := “2; 


, 
ParamText(IDStrHandle**, Stri, Str2, Str3); 
dialogP := GetNewDialog(AboutDialog, nil, pointer(-1)); 
1f dialogP = nil then 
begin 


doMessage( ‘Dialog crash!’, ‘We are dead...’, '', °’); 


ExitToShe11; 
end; 
initCursor; 
ModalDialog(nil, item); 
DisposDialog(dialogP); 
HUnlockCHandleCIDStrHandle2); 
end; 


procedure doQuit; 

begin 
DisposeWindowCADBWindow); 
TEDisposeCMgTextHandle?); 
Finished := true; 

end; (of proc) 


procedure doSave, 
begin 
end; 


procedure doSevels; 
begin 
end; 


procedure doPrint; 
begin 
end; 


procedure doPageset; 
begin 
end; 


procedure doMenuber; ((menuResult : LongInt2) 
var 

theMenu: integer; 

theItem: integer; 

daName: STR255; 

eccItem: integer; 

temp: GrafPtr; 

dummy: LongInt; (Desk Scrap result var) 
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ScrapReturn: OSErr; (TEScrap result var) 
TextLength: integer; 
ScrapLength: LongInt; 
begin 
theMenu := HiWord(menuResult); (menu) 
theltem := LoWord(menuResult); (item) 
case theMenu of 
App leMenu: 


begin 
if theItem = aAbout then 
doAbout 
else 
begin (must be DA) 
GetItem(myMenus[AppleM], theItem, daName); 
GetPort(temp); (protect against flacky DA} 
accItem := OpenDeskAcc(daName ) ; 
SetPortC temp); 
end; (else) 
end; (of AppleMenu) 
FileMenu: 
begin 
case theItem of 
f ADB: 
begin 
doADB; 
end; 
fSave: 
begin 
doSave; 
end; 
fSaveAs: 
begin 
doSaveAs; 
end; 
fPageSet: 
begin 
doPageSet; 
end; 


begin 
doPrint; 
end; 
fQuit: 
begin 
doQuit; 
end; 
otherwise 
begin 


end; 
end; (of theitem) 
end; (of FileMenu) 
EditMenu: 
begin 
if not SystemEditCtheitem - 1) then 
begin 
case theItem of 
eUndo: 
begin 
doMessage('Undo not available.’, '/, '', 49; 
end; 
еби: 
begin 
TECutCMyTextHandle?; 
dummy := ZeroScrap; 
ScrapReturn := TEToScrap; (update desk scrap) 
end; 
eCopy: 
begin 
TECopyCMyTextHandle); 
dummy := ZeroScrap; 
ScrapReturn := TEToScrep; (update desk scrap) 
end; 
ePaste: 
begin 
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ScrapReturn := TEFromScrap; 
TextLength := MyTextHandle**.teLength; 
ScrapLength := TEGetScrapLen; 
if CLongInt(TextLength + ScrapLength)) > 
longIntCTEMax - 1) then 
begin 
initCursor; 
paramTextC'Paste would exceed text 
edit 32000 buffer limit!’, 9,9, 609; 
ItemHit := StopAlert(AlertDialog, nil); 
end 
else 
TEPasteCMyTextHandle); 
end; ( of paste) 
eClear: 
begin 
TEDeleteCMyTextHandle); 
end; 
otherwise 
begin 
end; 
end; (of case) 
end; (of system edit) 
end; (of EditMenu) 
otherwise 
begin 


end; 
end; (of theMenu) 
HiliteMenu(0); (un-hilite selected menu) 
end; 


procedure doContent; ((ConEvent : EventRecord) 
(contentWindow : windowPtr);) 
var 
localPt, globalPt: Point; 
part: integer; 
myRect: Rect; 
control: ControlHandle; 
begin 
1f contentWindow € FrontWindow then 
SelectWindowCcontentWindow); 
globalPt := ConEvent .where; 
localPt := globalPt; (global coord of mouse) 
GlobalToLocal(localPt); (local coord of mouse) 
part := FindControlClocalPt, contentWindow, control); 


1f contentWindow = ADBWindow then 
begin 
SetPortCADBWindow); 
if part © Ø then 
begin (in control) 
end; 
if part = 0 then 
begin (content region) 
myRect := ADBWindow^ .portRect; 
1f PtInRectClocalPt, myRect) then 
begin 
TEClickClocaelPt, BitAnd(ConEvent .modif iers, 
ShiftKey) = ShiftKey, myTextHandle) 
end; (of ptInRect) 
end; ( of рагі=0 ) 
end; (of contentwindow) 
end; (of proc) 


procedure doDrag; ((GrabWindow : WindowPtr) 
GlobalMouse : point2;) 
begin 


DragWindow(GrabWindow, GlobalMouse, Üragárea); 
end; 


procedure doGrow; ((ResizeWindow : WindowPtr;) 
(Globalmouse : point;) 
(ZoomF 1g :Boolean); } 
var 
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newSize: LongInt; 
hsize: integer; 
vsize: integer; 
oldPort: GrafPtr; 
myRect: rect; 
tempLong: LongInt; 
1, t, r, b: LongInt; 
begin 
if (ResizeWindow  FrontWindow) then 
Se lectWindow(ResizewW indow) 


else 
begin 
if (ZoomF1g) then 
begin 
with ResizeWindow^ .portRect do 
begin 
tempLong := bottom - top; 
newSize :- BitShiftCtempLong, 16); 
newSize := newSize + (right - left); 
end; 
end 
else 
newSize := GrowWindowC(ResizeWindow, Globalmouse, 
GrowArea); 


if newSize © Ø then 
begin (grow the window} 
hsize := LoWord(newSize); 
vsize := HiWord(newSize); 
1f ResizeWindow = ADBWindow then 
begin 
with ResizeWindow .portRect do 
(Pre-Grow) 
begin 
SetRect(VCRect, right - (SBarWidth - 1), 
top - 1, right + 1, bottom - (SBarWidth - 2)); 
SetRect(HCRect, left - 1, bottom - 
(SBarWidth - 1), right - (SBarWidth - 2), bottom + 1); 
SetRect(GrowRect, HCRect.right, 
HCRect.top, VCRect.right, HCRect.bottom); 
end; (of with ) 
SizeWindow(ResizeWindow, hsize, vsize, 
TRUE); (new portRect) 
InvalRect(GrowRect); 
EraseRect(GrowRect); 
with ResizeWindow^.portRect do 
(Post Grow) 
begin 
SetRect(VCRect, right - (SBarWidth - 1), 
top - 1, right * 1, bottom - (SBarWidth - 2)); 
SetRect(HCRect, left - 1, bottom - 
(SBarWidth - 1), right - (SBarWidth - 2), bottom + 1); 
SetRect(GrowRect, HCRect.right, 
HCRect.top, VCRect.right, HCRect.bottom); 
SetRect(ViewRect, left + 4, top + 4, right 
- CSBarWidth - 1), bottom - C(SBarWidth - 125; 
end; (of with ) 


InvalRectCGrowRect); 

HideControl(CVContro1); 

HideControlCHContro!); 

MoveControl(VControl, VCRect. left, 
VCRect . top); 

MoveControlCHControl, HCRect.left, 
HCRect . top); 

SizeControl(VControl, SBarWidth, 
VCRect.bottom - VCRect. top); 

SizeControlCHControl, HCRect.right - 
HCRect.left, SBarWidth); 

ShowControl(VControl); 

ShowControlCHControl); 

ValidRect(VCRect); 

ValidRectCHCRect); 


MyTextHandle^^.ViewRect := ViewRect; 
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InValRect(ViewRect); 
end; (of if ResizeWindow) 
end; (of grow window stuff) 
end; (of if then newsize) 
end; ( of proc ) 


end. (of unit) 
unit MyADBGlobals; 


interface 


uses 
OSIntf, PrintTraps; 


const 
(window constants} 
ZoomBox = 8; (window type) 
MinWidth = 80; 
MinHeight = 89; 
mBarHeightGlobal = $BAA; 
GrayRgnLowMemGlobal = $9EE; 
sBarWidth = 16; 
TEMax = 32767; 
rsrc = ‘ADBx’; (creator bytes restype) 


(dialog stuff) 
AboutDialog = 256; 
MessageDialog = 258; 
AlertDialog = 260; 


— 


menu res id's) 

AppleMenu = 256; 
FileMenu = 257; 
EditMenu = 258; 


MenuCount = 3; 
AppleM = 1; 
FileM = 2; 
EditM = 3; 
(menu items) 
aAbout = 1; 
fADB = 1; 
fSave = 3; 
fSaveAs = 4 
fPageSet 
fPrint = 
fQuit = 8; 
eUndo = 1; 
4 


= 5; 
6; 


eCut = 3 
eCopy = 4; 
ePaste = 5; 
eClear = 6 


2 


versRequested = 1; 
numlock = 1; 
capslock = 2; 
scrolllock = 4; 


envBadVers = -5501; 
envVersTooBig = -5502; 


pe 
LongAndByte = record 
case integer of 
1: € longView: LongInt); 
2: ( byteView: record 
byte®: SignedByte; 
byte1: Signedbyte; 
byte2: Signedbyte; 
byte3: Signedbyte; 
end; ); 
end; 
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var 

(ny misc stuff) 
Finished: boolean; 
mBarHeight: Integer; 


(nenu stuff) 
myMenus: arrayl1..MenuCount] of MenuHandle; 


(rectangles) 
DragArea: Rect; (window drag area) 
GrowArea: Rect; (window grow area) 
Screen: Rect; (physical screen area) 
ADBWindowRect: Rect; (beginning window size) 
ZoomRect: Rect; (zoomed window size) 
HCRect, VCRect, GrowRect: Rect; (scroller rects) 
DestRect, ViewRect: Rect; (text edit rects) 


(dialogs stuff) 
ItemHit: integer; 
dialogflg: boolean; 


(Window Stuff) 
ADBWindow: WindowPtr; 
ADBWindowPeek: WindowPeek; 
myTextHandle: TEHandle; 
VControl: ControlHandle; 
HControl: ControlHandle; 
myPrint: THPrint; 


(ADB Stuff) 
theWorld: SysEnvRec; 
OSEr: OSErr; 
numberofADBs: integer; 
info: ADBDataBlock; 
buf: ADBOpBlock; 
ADBAddr: ADBAddress; 
device: byte; 


implementation 


end. 


Runtime lib 


Interface 116 
ON] V R PrintTraps.p 


[DN] V R OSintf.p 
[DINI VIR] My ADBGlobais 


(ОІМ(У(Е) ADB p 
мамл Ё 
Stuff 


tu 
Sun f 


Link Segments for our Project 
х ABR 


x 


ADB . RSRC 
222? ADBx 


Type ADBx = STR 
ADB Demo 1006 by Dave Kelly & Dave Smith \ØDver 2 MAR 1989 
х Multif inder Menu for Quit Cmd 


Type mstr = STR 
, 100 
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File 


* Multifinder Quit name 
Tupe mstr = STR 

‚ 101 
Quit 


Tupe FREF 
, 128 

APPL 0 

, 129 

TEXT 1 


Tupe BNDL 

, 128 

ADBx @ 

ІСКЕ 

0 128 1 129 
FREF 

@ 128 1 129 


* —— Multifinder events —— 


* bit 15 
* bit 14 
* bit 13 
* bit 12 
x 
x 
x 


reserved 

accept suspend resume events 
reserved 

can do background on null events 
multif inder aware 

(activates & deactivates topmost 
window at resume, suspend events) 


bit 11 


Type SIZE = GNRL 
уга 
.H 
4800  ;; $4800 = bits 14,11 set 
L 


128000 ;; (for 150K recomended) 
п 

80000 ;; (for 80К minimum) 

.I 


Type vers = GNRL 
yd 
‚Н 
01;; byte vers # in BCD 
10;; byte vers part 2 & 3 
50;; byte release stage $50=release 
00;; byte stage of non-release 
00 00 ;; integer country 0=US 
‚Р 
ү1.1 (05) 
.Р 
ADB Demo 1.1, @ by Dave Kelly & David Smith for MacTutor 1989 


Type vers = GNRL 

.H 

05;; byte vers # in BCD 

30;; byte vers part 2 & 3 

50;; byte release stage $50-release 
00;; byte stage of non-release 
00 00 ;; integer country 0=US 
Ер 

V5.3 

‚Р 

MacTutor Volume 5 Number 3 


x 


menus 


Type MENU 

* the desk acc menu 
‚256 

V 14 ;;арр1е menu 
About ADB Demo... 
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(- 


* the file menu 
,251 

File 
ADB /A 
(- 
(Save /S 
Save as.. 
Page Setup.. /U 
(Print.. /0 
(- 
Quit /Q 


* the edit menu 
, 258 

Edit 
(Undo /Z 
(- 
Cut /X 
Copy /C 
Paste /V 
Clear 


х — Dialogs — 
* About Box dialog... 
type DLOG 
,256 
About ADB Demo.. 
100 100 250 400 
visible NoGoAway 
l 
0 
256 


tupe DITL 

‚256 
3 
BtnItem Enabled 
112 235 141 284 
OK 


StatText Disabled 

10 88 141 289 

ADB Оето\20\020++ 

Queries System, blinks lights\@D°8\@D* 11007210023 


PicItem Disabled 
10 10 96 81 
128 


* Program Messages Dialog box... 
type DLOG 
,258 
Program Messages 
100 100 200 400 
Visible NoGoAway 
1 
0 
258 


tupe DITL 

‚ 258 
3 
BtnItem Enabled 
65 238 95 285 
OK 


StatText Disabled 
15 68 85 222 
^QN2D^ 11007210023 


IconItem Disabled 
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10 10 42 42 


1 


ÜFFF FFF8 OFFF FFF8 @FFF FFFB OFFF FFF8 


TYPE PICT = GNRL 
x — Alerts , 128 
.I 
* Program error alerts... 891 
tupe ALRT 195 254 281 325 
, 260 .H 
100 100 200 400 1101 А000 82А0 008Е 0100 0А00 0000 0002 
260 0002 4098 000A 00С3 00-8 BOFF 0148 00C3 
5555 00ҒЕ 00ҒҒ 0145 00C3 @@FE OOFF 0145 0000 
02Ғ7 0002 F700 02Ғ7 0002 Ғ700 02Ғ7 0002 
іуре DITL F700 02Ғ7 0002 Ғ700 02Ғ7 0002 Ғ700 B2F7 
,260 0006 Ғ000 000Е ҒС00 07Ғ0 0001 1Ғ80 Ғ000 
2 Q7FD 0001 7FCO Ғ000 07Ғ0 0001 ҒҒҒй Ғ000 
й08ҒЕ 0002 O3FF FCFD 0008 FEØØ 0207 FFFE 
BtnItem FDOO 09ҒЕ 0003 IFFF FF80 FE00 09ҒЕ 0003 
. 65 230 95 285 3FFF ҒҒЕй ҒЕ00 09ҒЕ 0003 7FFF FFF8 ҒЕ0 
OK @A02 0000 @1ҒЕ ҒҒ00 ҒСҒЕ 0008 0200 0003 
FDFF ҒЕ00 0А02 0000 OFFD FF00 COFF 0008 
StatText Disabled 0700 001Ғ FFFF 3FFF EOFF 0008 0700 007Ғ 
15 60 60 275 FFFE iFFF F8FF 0008 0700 OOFF FFFE IFFF 
Program Problem Alert: \@D°8* 172^3 FCFF 0008 0100 0ІҒЕ FF®2 27FF ЕСЕР 0008 
0100 @1FE FF02 FOFF F8FF 0008 0100 00ҒЕ 
* misc resources FF02 FE7F FOFF 0008 0200 003Ғ FEFF 019Ғ 
Tupe ICN# = GNRL EOFF 0008 0200 001Ғ FEFF 01Е7 COFF 000B 
‚ 128 (0) 0200 003Ғ FEFF 01Ғ9 80ҒҒ 0008 0200 0033 
.H FEFF @1FE 80FF 000A 0200 0060 FDFF 00C0 
0001 0000 0002 8000 0004 4000 0008 Е000 ҒҒ00 0807 0000 607Ғ FFFF FCCO FF00 0807 
0015 5000 0026 В800 0045 5400 0086 8200 0000 601Е FFFF F870 FFOO 0807 0000 6007 
0105 5100 0213 Е080 0428 0040 0810 0020 FFFF FOF8 ҒҒ00 0807 0000 6001 ҒҒҒҒ FOF8B 
1102 0010 2204 0008 4480 3Ғ04 8910 4082 ЕҒ00 0807 0000 6000 FFFF FOF8 ҒҒ00 0807 
4220 8041 2441 3022 1081 С814 081Е 7F8F 0000 6038 3FFF В050 ҒҒ00 0А06 0000 607С 
0402 3005 0201 0007 0100 8005 0080 6001 @FFF 30ҒЕ 0008 0700 0060 Ғ603 ҒЕЗ0 A8FF 
0040 1ҒЕ5 0020 021Ғ 0010 0407 0008 0800 0008 0700 0060 E301 FC30 5@FF 0008 0700 
0004 1000 0002 2000 0001 4000 0000 8000 0060 С000 7830 20FF 0008 0700 0060 0000 
* 1030 88FF 0008 0200 0060 FE00 0130 50FF 
0001 0000 0003 8000 0007 С000 BLOF Е000 900A 0200 0060 ҒЕ00 0030 ҒЕ00 0802 0000 
001Е Ғ000 003Ғ Ғ800 007Ғ ҒС00 ØØFF ҒЕ00 60ҒЕ 0001 30A8 ҒҒ00 0807 0000 6807 0700 
@1FF ЕЕ@@ O3FF FF80 O7FF FFCO OFFF FFEO 8050 ҒҒ00 0А06 0000 681F 8ҒС0 BOFE 0008 
1FFF ЕЕЕ@ 3FFF FFF8 ТЕРЕ FFFC FFFF FFFE 0700 006С 7FDF Ғ1В0 A8FF 000A 0200 0067 
TFFF FFFF SFFF FFFE 1FFF FFFC QFFF FFFF FEFF 0030 FEO0 0809 0000 63FF FFFE 31F4 
@ТЕЕ FFFF Q3FF FFFF @1FF FFFF @@FF FFFF 1000 0809 0000 307F DFFO 6046 3000 0809 
QO7F FFFF 003Ғ FE1F 001F ҒС07 000Ғ Ғ800 0000 381F 8FCO E045 5000 0809 0000 100 
0007 Ғ000 0003 Е000 0001 С000 0000 8000 0001 С044 9000 0809 0000 0Е00 0003 8044 
1000 0802 0000 0ТҒЕ FFFD 0009 0500 0001 
Туре ICN® = GNRL FFFF FCFD 0008 FEOQ0 0280 0004 FD00 9800 
, 129 (0) 0А00 FF00 F801 1901 4800 FF00 FEB! 1901 
.H 4500 FF00 FEO! 1901 4500 0008 ҒЕ00 0280 
OFFF FE00 0800 0300 0800 0280 0800 0240 0004 FDOO 08ҒЕ 0002 FFFF FCFD 0008 0200 
0800 0220 0800 0210 0800 03Ғ8 0800 0008 0001 FEAA FDOO 0802 0000 03ҒЕ 55FD 000A 
0800 0008 0801 0008 0802 8008 0805 4008 0600 0006 FEAF ЕА80 ҒЕ00 0А06 0000 0083 
080А А008 0815 5008 082А А808 0815 5008 5835 40ҒЕ 000A 0600 0018 0180 1ААб ҒЕ00 
080А А008 0805 4008 0802 8008 0801 0008 QA06 0000 3501 5015 50ҒЕ 000A 0600 006А 
0800 0008 0800 0008 0800 0008 0800 0008 82А8 2AAB FE00 BABE 0000 0570 5707 ҒАҒЕ 
0820 79Е8 0850 4528 0888 45Е8 09ҒС 4528 000А 0600 ОЛАҒ ААРА АСТА FE00 0А06 0003 
0А02 Т9Е8 0800 0008 0800 0008 OFFF ҒҒҒ8 5055 0558 ODFE 0008 0700 06А0 2А02 ABBA 
* 80FF 0008 0700 0060 3603 5415 40FF 000B 
üFFF ҒЕ00 OFFF FF00 OFFF FF80 OFFF FFCØ 0700 ØABØ 6B06 ABEA COFF 0008 0700 005Ғ 
@FFF FFEO ØFFF FFF® @FFF FFF8 OFFF FFF8 D5FD 5555 40FF 0009 0100 @AFC АА00 COFF 
ØFFF FFF8 @FFF FFF8 ØFFF FFF8 @FFF FFF8 0009 0100 ODFC 5500 40ҒҒ 0009 0100 ОҒҒС 
QFFF FFF8 ØFFF FFF8 @FFF FFF8 OFFF FFF8 ҒҒ00 COFF 0002 Ғ700 02F7 0002 Ғ700 02F1 
ØFFF FFF8 ØFFF FFF8 @FFF FFF8 @FFF FFF8 0002 Ғ700 02Ғ7 0002 Ғ700 А000 BFAD 0083 ss 
ØFFF FFF8 @FFF FFF8 @FFF FFF8 @FFF FFF8 FF oa! 
üFFF FFF8 @FFF ҒҒҒ8 OFFF FFF8 OFFF FFF8 ==, 
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New users of the Macintosh are sometimes fascinated with 
the use of pull-down menus. Even experienced users head 
straight for the menu bar when they get a new program to see just 
what it does. Usually the menus get checked out before the 
manual does. Hierarchical menus added additional capabilities 
for the user. A little over a year ago, we began seeing the 
appearance of pop-up menus as another interface for the user. 
The various versions of BASIC cover the regular pull-down 
menus pretty easily. Hierarchical menus and pop-up menus are 
now being used in most of the software which is now being 
released. This column will attempt to explain how to set up pop- 
up menus using True Basic. Similar methods for implementing 
may be used in ZBasic or any other language for that matter. The 
method is about the same in whatever language is used and since 
many of the commands come from the Macintosh Toolbox. It 
should be pointed out that you must be using System 4.1 or 
greater for Hierarchical or pop-up menus to work. You should 
upgrade to the latest version (6.02). 

It is advisable to know when it is appropriate to use pop-up 
menus. Apple recommends that pop-up menus be used for 
setting values or choosing from lists of related items. A pop-up 
menu could “pop up” anywhere (its location is global), but 
usually used in a dialog. The indication that there is a pop-up 
menu is that there is a box with a one-pixel thick drop shadow 
which is drawn around the current value. When the user presses 
the mouse button which pointing within the box, the pop-up 
menu appears with the current value checked and highlighted. 
Other than that, the pop-up menu acts just like any other menu. 

The Macintosh ROM takes care of the pop-up menu action, 
but you must take care of drawing the shadowed box which 
indicates that there is a pop-up menu. You must take care of 
inverting the title when the menu is showing. The current value 
should appear in the pop-up menu when it is selected. Apple also 
recommends that you NOT use Hierarchical pop-up menus. You 
should consider very carefully if you really need to use a pop-up 
menu. Some features could better be implemented with icons or 
with the normal menus in the menu bar. Don’t use commands in 
your pop-up menus unless you have to. If you do use commands, 
you should duplicate the item in the menu bar menus. “All 
commands that are in general use throughout the application 
should appear in the menu bar. This assures that the most 
important commands are always visible and available to the 
user”. (refer to “Commands in pop-up Menu” from HI Update 
#13). 


How it works.... 


Inside Macintosh Volume. V menu manager routines added 
one new ROM function for doing pop-up menus. The function 
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PopUpMenuSelect allows pop-up menus to be handled and 
created anywhere on the screen. Since the pop-up menu re- 
sources are handled the same as for other menus, they may 
contain color and submenus. The True Basic demo program has 
a basic event loop structure which can be used as a basic skeleton 
for other applications if you want. The libraries which are used 
come from the True Basic Macintosh Programmer’s Kit which is 
essential for any serious Macintosh program development. 

To implement pop-up menus, the program uses an array to 
set up the menu items. These items are declared in the PopItem$ 
array which is dimensioned near the beginning of the program. 
SysEnvirons is called to see if the system has the pop-up menu 
routines. If it doesn’t, the program quits. It would be better to 
display a dialog to warn the user why the program quit. In 
addition to setting up the menu bar, the menu used in the pop-up 
is created and stored in a resource where MyMenus$(4) is the 
handle to the menu resource. After the menu resource is created, 
the only thing left to do is draw the pop-up title and shadowed box 
then wait for an event. 

The top and left corner of the pop-up are assigned at the 
beginning of the Drawpopup routine so that you may place the 
pop-up wherever you like. Be sure to leave room for the title. The 
routine figures out the width of the Title and longest menu item 
and draws them at the appropriate locations. When the pop-up 
menu Comes up, the shadowed box should always line up with the 
pop-up menu. This is simple, but you can get confused unless you 
realize that the shadowed box and title are drawn with local 
window coordinates, but the pop-up menu location is determined 
by global screen coordinates. It is necessary to convert this 
location from local to global to tell the pop-up select routine 
where the menu should go. If the window gets moved (by 
someone dragging it), remember that the global coordinate is 
now different, but the local coordinate stayed the same. 

You determine that a pop-up menu needs to be handled by 
checking to see if the mouse was clicked within the shadowed 
box. The GetNextEvent function returns the point where the 
click occurred. This point is compared with the PtInRect routine 
to determine if the point is within the shadowed rectangle where 
the pop-up will appear. If so then the program handles the pop- 
up event by calling the PopUpMenuSelect routine. PopUp- 
MenuSelect takes the menu handle, the left and top coordinates 
where the menu will appear, and the currently selected menu item 
and handles the menu by displaying the menu then returns the 
item number of the menu item that was selected. That item is then 
redrawn into the shadowed box and becomes the newly selected 
item. The program should then handle whatever action or flag the 
menu item should do. 

This process is simple enough after seeing a few examples. 
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The main problem with pop-up menus as with other controls that 
you may want to use is that you must be careful not to clutter up 
the window too much. The graphic design of the interface is just 
as important as the code that is written. That's why there will 
always be a demand for good programs even though HyperCard 
and other tools make developing programs easier. 

By the way, some of the programming in True Basic can be 
simplified by using the TrueWindows Library. The problem 
comes when you want to create an application using the Runtime 
package. The Binder utility asks for the compiled libraries and 
then the compiled program and outputs them to an application 
that contains the True Basic interpreter. If you use libraries that 
have calls or functions with the same name, they may work fine 
until you bind them together into an application with Binder. 
Binder gives an error when putting the libraries together which 
says that you have more than one call with the same name. This 
could happen if you are using TrueWindows and the other 
Macintosh Programmer’s Kit routines (like the ones used in this 
program). You may be able to get around this by going to the 
source code files and removing the duplicate name and recompil- 
ing the library. Be sure to keep it separate from the original so that 
they don’t get mixed up or someday you may need a routine that 
you deleted and wonder why things don’t work. 

I set up my copy of the True Basic runtime application with 
my own icon and when I create an application, the information is 
already set up provided that I want to use the same one each time 
I make a new application. Usually you will want them to be 
different. I use the Prof. Mac icon for any applications that I make 
for MacTutor. 


! PopUp Menu Demo 

! True Basic version 2.01 

! Requires True Basic Macintosh Developer's ToolKit Libraries 
! by Deve Kelly 

! 01989 MacTutor 


REM Open up libraries 
LIBRARY "MenuLib*^ 
LIBRARY “WindowL ib*” 
LIBRARY “DeskLib*? 
LIBRARY “Еуел 1057 
LIBRARY “QuickLib*” 
LIBRARY *DataLib*^ 
LIBRARY “Мас! ib*” 
LIBRARY “System*” 


Menu Manager 

Window Manager 

Desk Manager 

Event Manager 

Quickdraw 

Desk Acc and system calls 
True Basic event contro] 
System Calls 


REM following variables are used globally throughout program 
DECLARE DEF NIL$, 

POINTERS, screenBits$, bounds$, top, left, bottom, right, TopLef t$,H,V 
DECLARE DEF OpenDeskAcc,NewW indow$, SystemEdit 

DECLARE DEF MenuSelect,PtInRect, TrackGoAway 


DIM MyMenus$C 1:4) 

DIM PopItem$C1:3) 

CALL SysEnvironsCsysEnvRec$, status) 

revision 

CALL UnpackEnvironsCsysEnvRec$, envversion, 

machine, sysversion, processor, 

hasFPU,hasColorQD,keyboardtype,atversion, sysvrefnum) 

IF susversion=0 then ! Do we have the right ROM? 
STOP 

END IF 

CALL TakeMac 

its own thing 


! Get current system 


! turn off True Basic and let the program do 


576 


LET everyevent=- 1 ! event mask for all events 
LET doneF lag=8 ! this flag is set when 
program ending has been selected. 
LET z$=bounds$(screenBi ts$) 
screen. 

CALL setrect(r$, lef t(z$)+4, top(z$)+44, right(z$)-4, bot tom(z$)- 
4) 

CALL setrect(dragrect$, 4,24, right(z$)-4, bottom(z$)-4) 

LET myWindow$=NewW indow$(NIL$,r$, “Sample”, 1,0, POINTERÉC- 

1), 1,8) 

! Create a window 

CALL SetPor t(myW indow$) 
CALL SetUpMenus 

CALL Drawwindow 


! Get the size of the 


I Access the new window 
! Turn on menus 
! Set up window info 


! Main Event Loop 


DO 
CALL SystemTask ! Handle System tasks/DAs 
CALL GetNextEventCeveryevent, theEvent$, eResult) 
! check for events 
IF eResultO8 then ! if no event error occurred then... 
CALL UnpackEvent( theEvent$, what, ness, when, where$, mod) 
SELECT CASE what 
! what represents the kind of event that occurred. 
! mouse down event occurred 
CALL FindWindow(where$, whichW indow$, wResult) 
SELECT CASE wResult 
CASE 1 ! Event was in the menu bar 
LET mResult=MenuSe lect (where$) 
CALL DoMenuCmResul t ) 
CASE 2 ! Event was in a system window 
CALL SystemC] ick( theEvent$, whichW indow$) 
! Pass the event to the system 
CASE З ! Event was in content region of a window 
CALL GlobalToLocalCwhere$) 
! convert coordinates for the window 
IF PtInRectCwhere$, PopRect$)=1 THEN 
! see if popup was selected 
CALL PopUpEvent ! if so, handle the 


END IF 
CASE 4 ! Event in the window's drag region 
CALL DragWindow(whichWindow$, where$, dragrect$) 
CASE 6 ! Event in go-away region of active window 
LET doneF lag=TrackGoAway(whichw indow$, where$) 
CASE else 
END SELECT 
CASE 6 ! update event occurred 
CALL Packb(w$, 1,32, mess) 
CALL BeginUpdate(w$) 
CALL Drawwindow 
CALL DrawPopUp 
CALL EndUpdate(Cw$) 
CASE else 
END SELECT 
END IF 
LOOP until doneFlag<>8 


popup event 


! anything else? 


CALL DisposeW indow(myW indow$ ) ! Throw away window handle 
CALL ClearMenuBar ! Clear Menus 
FOR i=Lbound(MyMenus$) to Ubound(MyMenus$) 

CALL DisposeMenu(MyMenus$C i )) 


NEXT i 

CALL GiveMac ! Return control back to 
True Basic 

STOP ! End the program 


SUB DrawWindow 
CALL textfont(2) 
CALL textsizeC 12) 
CALL textface( 1) 
CALL textmodeC2) 
CALL movetoC 10,20) 


Draw message in window 
Set font to New York font 
Set size to 12 point 

Set text to bold 

Set to copy mode 
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END 
SUB 


END 
SUB 


CALL DrawString(*True BASIC Version 2.0 PopUp Menu demo”) 


CALL textfaceC0) ! Set text to plain 
SUB 
DoMenu(Ccode) ! handle Menu events 


CALL Packb(s$, 1,32, code) 

LET MenuNumber=Unpackb(s$, 1, - 16) 

LET Menuitem = Unpackb(s$, 17,- 16) 

SELECT CASE MenuNumber 

CASE 1 ! Apple Menu 
CALL GetItemCMyMenus$C 1), Menul tem, name$) 
LET mrefNum-OpenDeskAcc(name$) 
CALL SetPort(mywindow$) 

CASE 2 ! File Menu 
LET doneF lag=- 1 

CASE 3 ! Edit Menu 
(ЕТ z-SystemEdit(Menuitem* 1) 

CASE else 

END SELECT 

CALL HiliteMenuC0) 

SUB 


SetUpMenus 
DECLARE DEF NewMenu$,StringWidth ! Declare variables used 
DECLARE DEF GetFontInfo$ ! in toolbox functions 


LET MyMenus$C 1)-NewMenu$C1,chr$(20)) ! The first menu is 
CALL AddResMenu(MyMenus$(1),“DRVR”) ! Apple menu. 
LET MyMenus$(2)=NewMenu$(2,“File”) ! File menu is second 
CALL AppendMenuCMyMenus$ (2), “Quit” 
LET MyMenus$(3 )=NewMenu$(3, “Edit” ! Next the Edit menu 
CALL AppendMenuCMyMenus$ C3), Cut”) 
CALL AppendMenuCMyMenus$ C3), “Сору”2 
CALL AppendMenuCMyMenus$ C3), "Paste^) 
LET PopTitle$-"PopUp Menu Title: ^" | Save pop up title 
LET MyMenus$(4)=NewMenu$(4,PopTitle$) ! Create pop up menu 
LET Роріќет$ С 1)="Item 1" 
LET Popitem$(2)=“Item 2" 
LET Popitem$(3)="Item 3" 
LET NoOfPopItems-3 
LET PopI tem=1 
FOR i=1 to 3 

CALL AppendMenuCMyMenus$(42,Popitem$Ci)) ! Add popup 


items 
NEXT i 
FOR i=Ibound(MyMenus$) to Ubound(MyMenus$)-1 ! put the 
menus into 
CALL inser tMenuCMyMenus$(i), 0) ! the menu bar 
NEXT i 
CALL InsertMenu(MyMenus$(4),-1) ! Add pop up menu 


CALL CheckItemCMgMenus$(4),PopItem, 1)  ! check default 


item 


REM Get maximum length of PopUp items 

CALL TextFont(@) ! Set to system font 
CALL TextSizeC12) ! Set to 12 point size 
CALL GetFontInfoCFontInfo$) 

LET ascent = Unpackb(fontinfo$, 1,- 16) 

LET descent = Unpackb(fontinfo$, 17,- 16) 

LET widMax = Unpackb(fontinfo$, 33, - 16) 

LET leading = Unpackb(fontinfo$, 49, - 16) 

(ЕТ MaxItemLength-0 


FOR i=1 to NoOfPopI tems 
LET strwidthzStringWidth(Popitem$Ci»?) 
IF StrWidth»MaxItemLength then LET 


Мах І temLength=StrWidth 


ЕМО 
SUB 


NEXT i 

CALL DrawPopUp 
CALL DrawMenuBar 
SUB 


DrawPopUp 
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CALL TextFont(C0) ! Set Font to Chicago (System) 
CALL TextSize( 12) ! Set Size to 12 point 
LET Popup top= 100 ! Top of Popup menu 
LET Popup lef t=200 ! Left of Popup menu 


CALL SetRect(PopRect$, Popupleft,Popuptop, 
Popupleft*5*MaxItemLength*13, Popuptoptascent+ descent: 
leading* 1) 

CALL FrameRect(PopRect$) ! Draw currently selected item 

CALL MoveTo(Right(PopRect$), Top(PopRect$)+1) 

CALL LineToCRight(PopRect$), Bot tom(PopRect$)) 

CALL MoveTo(Lef t(PopRect$)+1,Bottom(PopRect$)) 

CALL LineToCRight(PopRect$), Bot tom(PopRect$)) 

LET StrWidth=Str ingWidthCPopTitle$) 

LET xlocation=Lef t(PopRect$)-StrWidth 

LET ylocation=( Top(PopRect$)+Bot tom(PopRect$))/2+Cascent- 
descent )/2 

CALL MoveTo(xlocation, ylocation) 

CALL Drawstring(PopTitle$) ! Draw the Popup menu title 

CALL SetRect(InvertTitleRect$, xlocation- 

8, Top(PopRect$)+ 1,Lef t(PopRect$), Bot tom(PopRect$)) 

LET xlocation=Lef t(PopRect$)+13 

CALL MoveTo(xlocation, ylocation) 

CALL Drawstr ing(Pop! tem$(PopItem)) 

! Draw the currently selected item 
END SUB 


SUB PopUpEvent 
DECLARE DEF PopUpMenuSelect ! Declare function 
CALL InvertRect(InvertTitleRect$) ! invert popup title 
LET TempPoint$=TopLef t$CPopRect$) 
CALL LocalToGlobal(TempPoint$) ! Change to global coords 
LET PopTop=V(TempPoint$)+1 
LET PopLef t=H( TempPoint$)+1 
LET 
Result-PopUpMenuSe lect (MyMenus$(4), PopTop,PopLef t, Pop! tem) 
! Do the Popup 
CALL Packb(s§, 1,32,Result) ! Get the menu result 
LET MenuNumber=Unpackb(s$, 1,-16) 
! Ignore Menunumber, we know which menu this is 
(ЕТ Menuitem = Unpackb(s$, 17,-16) ! Get the menu item 


IF Menul tem=PopI tem THEN 
CALL Inver tRect(InvertTitleRect$) 
! Invert the title to normal if old item selected 
ELSE 
CALL CheckI tem(MyMenus$(4),PopItem,@) ! uncheck last 
item 
CALL CheckI tem(MyMenus$(4),Menultem, 1) ! check new item 
CALL EraseRect(PopRect$) ! Draw the current menu item 
CALL FrameRect(PopRect$) 
CALL MoveTo(xlocation, ylocation) 
CALL Drawstr ing(Pop! tem$(PopI tem) ) 
CALL Inver tRect(InvertTitleRect$) 
SELECT CASE MenuI tem ! Handle menu event 
CASE 1 
REM Do Item 1 
LET PopI tem=Menu! tem 
CASE 2 
REM Do Item 2 
(ЕТ PopI tem=Menul tem 
CASE 3 
REM Do Item 3 
LET PopItem-MenuItem 
CASE ELSE 
END SELECT 
CALL MoveTo(xlocation, ylocat ion) 
CALL TextFont(6) ! Set font to Chicago (System) 
CALL Drawstring(PopItem$(PopItem)) ! draw selected 
popup item 
END IF 
END SUB 
END 
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Sounding Off with MS QuickBasic 


Playing Digitized Sounds with MS QuickBasic 

[Ron Butcher bought his first computer in November of 
1984; luckily, it was a Macintosh. He first learned BASIC on a 
DEC minicomputer at DeSoto, Inc., where he works as an 
Industrial Chemist. He discovered programming on the Mac with 
MS Basic 1.0 in December of 1984.] 

There have been many occasions when I wished I could use 
digitized sounds instead of Basic’s SOUND statements for 
enhancing programs I was writing. Judging from questions seen 
in magazines and on BBS’s from other Basic programmers, I 
guess I wasn’talone. AsI have a game written in Basic that could 
benefit greatly from sound effects, I decided to look into this 
further. This lead me to some heavy reading in Inside Macintosh. 

Well yes, you can play digitized sounds from Basic, using 
the free form synthesizer in the Mac, and very handy Library 
routines implemented in QuickBasic. These routines allows you 
to implement Operating System ROM traps which return infor- 
mation in a Parameter Block. Many of these functions are used 
by the File Manager and Device Manager, such as _Open, 
_Close, Read, Write, etc. I suggest you beg or borrow (don't 
steal) a copy of Inside Mac so you can follow some of this 
background information. 


Sound Background 
To play digitized sounds, we need to utilize the Free-Form 
Synthesizer. Inside Mac's Pascal structure looks like this: 


Type FFSynthRec = RECORD 


node: INTEGER; (alwaus ffMode) 

count: Fixed;(“sizing? factor) 
waveBytes: FreeWave (waveform description) 
END; 


FFSynthPtr = “FFSynthRec; 
FreeWave= PACKED ARRAY OF Byte; 


Let’s translate this for our use with QuickBasic. We need to 
allocate a block of memory for the size of the sound involved, and 
save the first 6 bytes of this block for the mode (integer ffmode, 
which is always 0 for the free form synthesizer), and count (fixed 
point, which is how we tell the sound driver at what “speed” to 
play the sound). Inside Mac also tells us that we can play a free- 
form sound by making a Device Manager Write call with the 
following parameters: ioRefNum must be -4 (the Sound Driver), 
ioBuffer must point to the synthesizer buffer, and ioReqCount 
must contain the length of the synthesizer buffer. The sound data 
needs to be read into the buffer, the mode and count entered as the 
first six bytes, and that buffer (FFsynthRec) is then written to the 
Sound Driver. 
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The count constants, being fixed point, threw me a curve. 
When count is equal to 1, the “sizing factor” is 1, and sounds are 
played at the 22KHz sampling rate. But how to get .5 (11 Khz), 
.33 (7.4Khz), and .25 (5.5Khz) presented a minor challenge. 
Fixed point numbers on the Mac are 32 bits long. The high word 
is the integer, and the low word the fractional part. The bit 
representation is shown in Fig. 1. For example, 1.0 would be 
represented as: 0000000100000000. 1.5 would be represented 
as: 00000001 10000000. From this we get the count& hex values 
of &H10000 for 1.0, &H8000& for .5, &H5555& for .33, and 
&H4000 for .25. The actual sample rate is taken from this 
equation: 

frequency (Hz) = 1000000 / (44.93 * (wavelength / count) 


) 
This is derived from the fact that the sound is created by 


starting play at the first byte, and skipping ahead count bytes 
every 44.93 microseconds; so with the smallest wavelength (1 
byte) and acount value of 1, the frequency works out to 22,256.8 
Hz, which is the highest quality sampling rate of most sound 
digitizing software. 


Fixed Point Number Representation 


0 


15 
CCITTCCIMEENEREREN 


Integer (high word) 
13 0 


_1]4[ | +++ mmaa 


Fraction (low word) 


figure 1. 


The ToolBox MBLC 

The following illustrates the formats for the Operating 
System (OS) calls needed to be made to implement the Sound- 
Player program. The calls we are going to make are register based 
calls. As a general rule, OS calls are register based, and ToolBox 
calls are stack based, but there are exceptions on both sides (here 
I mean Mac ToolBox, not QuickBasic ToolBox calls). You can 
tell one Trap from another by checking bit 11 of the Trap word. 
If it is set (1), then it is a Toolbox Trap word; if bit 11 is not set 
(0), then the call is an OS Trap word. For example, traps starting 
with AO are OS traps, and traps starting with A9 are ToolBox 
traps. 

The generic register based QuickBasic call is: 
Too1Box^R^, Trap, ReturnArray& (8), Ca0&), Ca 1&2, CdO& ), Cd 1&2, Cd2&) 
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For our calls having values passed to and from a Parameter 


Block, the call in our program will look like this: 
Paramk=VARPTR(ParamBlock%$(0)) 


ToolBox *R^,Trap$,Reg&(0), CParam&) 

Per Inside Macintosh, after we pass the appropriate values to 
the Parameter Block, we can make the call with a0 pointing to the 
address of the Block (Param&). Values are first passed to the 
appropriate registers (a0&.. etc) and ReturnArray Reg&() will 
contain the values passed to them after the call is made. Any 
errors will be returned in d0 (Reg&(2)).To get a pointer to our 


sound record, I' ve used NewPointer to allocate the blocksize: 
NewPtr$-&HA 1E 


ToolBox “К” NewPtr%,Regk(O),, (5126) Be ate 
The size of the soundrecord is contained in Siz&, and the 


pointer to the record will be return in a0 (Reg&(0)). To manipu- 
late the sound resources (snd ), I’ve used a slightly different 
technique. I first use the QuickBasic ToolBox call GetHandle- 
Size to obtain the size of the snd resource. NewPointer is then 
used to allocate the appropriate soundrecord. To coerce the snd 
resource Handle to a Pointer, I used BlockMove to transfer the 
sound information referenced by Handle h& to the block of 
memory pointed to by NewPointer. I could then release the 
memory used by the resource and the Handle using ReleaseRes. 
Note that in actuality, the header bytes of an snd resource contain 
resource info, including the length of the sound data (this length 
varies depending on the snd format; format 1 was developed for 
the Sound Manager, and format 2 is for HyperCard). I’ ve ignored 
these bytes for simplicity’s sake, but you can use them to your 
advantage in your own program. The program is set up to only 
open resource files of type SFIL and STAK, but you can expand 
on this to include other types. The same goes for the sound data 
files, which I have limited to type FSSD for this program 
example. 


The File and Device Manager Routines 

The following formats are for using File Manager _Open, 
_Close, and GetEOF calls. The —> indicates values to be passed 
to a routine, the <— indicates values returned by the routine, and 
«—» indicates values passed to and from the routine. The Parame- 
ter block size required is different for different calls, but the 80 
byte array size used in the program is large enough for the calls 
we'll be implementing. The parameter block will be stored as an 
integer array. 


FUNCTION PBOpen, PBClose, PBGetEOF CparamBlock: ParmBlkPtr; 
async: BOOLEAND : OSErr; 


-Open, Close, .GetEOF 
(_Close only uses ioCompletion, ioResult, and ioRefNum) 
(-GetEOF additionally uses ioMisc, which returns the logical 
end of file, or filelength) 
Paremeter block 


- 12 ioCompletion pointer 
(- 16 ioResult word 

-) 18 ToNamePtr word 

-) 22 ioVRef Num pointer 
-) 24 ioRefNum long word 
(- 26 ioVersNum long word 
-) 21 ioPermssn word 

‹-› 28 ioMisc long word 
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To open a sound data file, we need only to pass the address 
of the Pascal string of the file pathname (from FILES$ and 
SADD function) to ioNamePtr, and call the _Open Trap. 
ioRefNum will be returned at byte 24 of the array. _GetEOF, 
which requires ioRefNum, can then be called to get the length of 
the file. You can also set byte 27 to 1 to make the Open call read 
only, just to be on the safe side. I used the QuickBasic B2PStr call 
to coerce the Pascal string from the Basic string. You could also 
use the Pstr$=LEN(Bstr$)+Bstr$ method. 

Here's the format for a File Manager _Read call and Device 
(or File) Manager _ Write call: 


FUNCTION PBWrite, PBRead CparamBlock: ParmBlkPtr; async: 
BOOLEAN) : OSErr; 


Irap macro Write, Read 

Parameter block 
-) 12 ioCompletion pointer 
(- 16 ioResult word 
-) 24 ioRef Num word 
m 32 ioBuffer pointer 
-) 36 ioReqCount long word 
(- 40 ioActCount long word 
-) 44 іоРоѕМоде word 
C) 46 ioPosOffset long word 


Toread in all the sound file data into the buffer, we now need 
to give the Parameter block the address of the soundbuffer in 
ioBuffer, and how many bytes we want read in ioReqCount. 
Since all reads will be from the beginning of the file, ioPosMode 
and ioPosOffset are zero. ioRefnum is still the file reference 
number. When the Write call to the Sound Driver is made, 
ioRefNum is the Driver's reference number, -4 (&HFFFC). As 
we're set up here, the Write call is synchronous, that is, the 
program will not continue until the write call is finished. You can 
make an asynchronous call which allows your program to con- 
tinue while the sound is being played by polling ioResult. This 
word returns a positive value while the sound is being played. 
This way you can limit certain operations of your program 
through a WHILE-WEND or IF-THEN operation. To make an 
asynchronous call, set bit 10 of the trap word; this would make 
the Write trap &HA403, for example. I’ve found the asynchro- 
nous calls to be fairly touchy when being implemented from 
Basic. You can use КІШО to stop any current sound being 
played and cancel every pending asynchronous call. 


Bells and Whistles 

The subroutine “Drawgraph” allows you to graphically 
illustrate the sound wave that has been opened for play. As byte 
values go, &H80 (128 decimal) represents 0 amplitude, while 
&HFF (255 decimal) represents 100% positive amplitude, and 0 
represents 100% negative amplitude (See fig. 2). The routine 
takes a y axis sample every ScreenWidthVMilelength bytes in order 
to have an even sampling over the width of the screen. Since the 
y values will be drawn down with respect to the screen coordi- 
nates, I implemented a simple inversion routine so the plot could 
be viewed right side up with respect to the actual wave. Although 
compressed, the graph that is drawn gives a decent visual 
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representation of the sounds actual waveform, such as that which 
might be seen on an oscilloscope in real time. 


c Free Form Wave —- 


$FF 
=| 
"INE 
$00 Time 
figure 2. 
Thanks for the Memory 


The main problem I ran into when setting up this program 
was finding an efficient way of allocating memory for the sound 
record, FFSynthRec. For a sound call, the memory block should 
ideally be locked until the sound call is finished, and then 
disposed of to free up the memory in the heap. I used one of 
QuickBasic's new features, the ToolBox calls, to use the New- 
Pointer function to grab a non-relocatable block of memory to 
hold the sound record. In my initial version of the program, I used 
an array to hold the sound record. This works, but really slows 
things down a lot. The most efficient use of the array would be to 
dimension a dynamic array only to the size needed as dictated by 
size ofthe sound file and erase it after use. Itis best to have a static 
array for the sound record, because some pretty weird things 
happen if that array shifts around in memory while being written 
to the Sound Driver. Ah, there's the rub.... you can't use static 
arrays in the interpreter, and if you use them in the compiler, you 
can't erase and resize them. 

I've left a few items off of the program that may be imple- 
mented later, such as sound file decompression, and the ability to 
save sound resources as data, and visa-versa. Compressed sound 
data files have the header “НСОМ”, and I've flagged this 
condition with a BEEP sound, as I haven't figured out the 
decompression algorithm yet. Error handling is also at a mini- 
mum. For the ToolBox calls, Reg&(2) returns the error code, 
which is O for no error. The OS errors returned can be many and 
varied, so you may want to show the error number in an Alert and 
stop the program. When compiling the program, check the 
“Маке all arrays Static" and “Process Runtime Events” box. You 
can uncheck the boxes for “Use Default Menu" and “Use Default 
Window". 

Being able to use the File Manager calls has other advan- 
tages which enable you to manipulate files in ways you can't do 
with normal BASIC commands such as INPUT, OUTPUT, 
WRITE, etc. Using the ToolBox calls, I' ve been able implement 
MacBinary in a telecom program, and write a disk cataloging 
utility, for example. Hopefully this program will shed some light 
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on using the sound driver from BASIC, and give you some ideas 
on how to use digitized sound in some of your own applications. 


‘ SoundP layer 

' Plays digitized sounds from snd resources 
‘ end sound data files using 

‘ MicroSoft QuickBasic 1.0 

° 2/26/1989 


CLEAR, 1000008 

DIM Paramblock$(39),scr$(3),bar$ (3), pt$(22,r C3) 
DIM PHS$( 208), id$ C200) 

DIM a&(5) 

‘ Trap calls 

RITES-&HA2Q3 : Ohpen$-&HA000 

Dread$-&HA002 :Klose$-&HA00 1: GetEOF$-&HA2 11 
NewPtr$-&HA01!E : DisposeP tr3=&HA@ IF 
‘Initialize variables and constants 
FFsunthPtr&=@:Param&=0:Siz&=0:h&=0:S&=0:ResH&=0 
0 ldbut%=8 : butnum%=8 : Tag&=08 :state3=0 
х0%-0:,0%-0:,%-0:х%-0 

true%=- 1: false%=9:GotPointer%=false%:er%=0: 
Menu! tem%=@ : MenuCho ice%=8 
ForkOpen&=false% : gotresource%=false% 

num%=2 : num 15=0:геѓ&=0: 10%=0: act ionk= 
type$="snd ":nan$-"":F$2"":6$-2"":pic$-"" 
1f d&=8 : 1=8: count&=8 : res id%=8 
TwentyTwoK&-z&H10000& ' count values 
ЕТеуепК&=&Н8000& 

SevenK&-&H5555& 

FiveK&-&H40008& 

ToolBox *i^ 

WINDOW CLOSE 1 

MENU 1,8, 1, "File" 

MENU 1, 1, 1, ^0üpen Sound Data” 

MENU 1,2, 1, "Open Sound Resource” 

MENU 1,3,0, "Drew Sound Graph’ 

MENU 1,4, 1, “Quit” 

CndKey 1, 1, *0* 

CmdKey 1,2, “R? 

CmdKeu 1,3,2G” 

CmdKey 1,4,2Q” 

Sheight=SYSTEM(6) 

Swidth=SYSTEM(5) 

WINDOW 2, **, (58, 190)- CSwidth-32, Sheight-772,3 
BUTTON 1, 1,722 KHz’, €25,25)-(€ 108, 48),3 
BUTTON 2,2,"11 KHz^,(25,602-C 100, 75),3 
BUTTON 3,1,77.4 KHz^,(25,952-C100, 1102,3 
BUTTON 4,1,%5.5 КН2”,(25, 1302- C 100, 1452,3 
BUTTON 5,0, “Play”, С 130, 75 )-С 190, 100) 
SetRect ѕсг%С0), 200,6, 400, 158 

SetRect баг%С0), 399,6, 4 15, 158 

г5С0)=75 

r$(1)=130 

r$(2)=100 

r$(3)=190 

inSetRect r$(0),-4,-4 

oldbut$22:count&sE levenK& 
linenum$=@ : top%=8 : S&=0 : іп%-0 

NewScrol] S&,bar%(@), 1, 1, 1, 1 

InactiveScroll Sk 

PICTURE ON 

PENSIZE 3,3 

FRAMEROUNDRECT VARPTR(r&(8)), 16, 16 
PENNORMAL 

ERASERECT VARPTR(scr%(@)) 

FRAMERECT VARPTR(scr%(@)) 

PICTURE OFF 
pic$=PICTURE$ 
PICTURE ON : 
refresh 


PICTURE OFF 
ON MENU GOSUB MenSelect : MENU ON 
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ON DIALOG GOSUB ChoiceWait : DIALOG ON 


UserWait: 

WHILE true% 

hittest 

ScrollText S&,scr$C0), PHS$C 1), top%,num 1%, 1 inenum$,3 
WEND 


ChoiceWait: 
MENU STOP : MOUSE STOP 
act ion%=DIALOGCO) 
IF action$-5 THEN CALL refresh 
IF action$ 1 THEN 
MENU ON : MOUSE ON 
RETURN 
END IF 
ON action$ GOSUB HandleButton 
MENU ON : MOUSE ON 
RETURN 


HandleButton: 
butnum%=DIALOGC 1) 

IF butnum%=oldbut® THEN RETURN 
IF butnum® © 5 THEN 
BUTTON butnum, 2 
BUTTON oldbut$, 1 
oldbut$=butnum% 

END IF 
SELECT CASE butnum% 
CASE 1 
count&=Twen ty Twok& 
CASE 2 
count&=E levenK& 
CASE 3 
count&-SevenK& 
CASE 4 
count&z-F i veK& 
CASE 5 
GOSUB writefork 
END SELECT 
RETURN 


openDataF ile: 
F$-FILES$C1, “Ғ550%):ІҒ Ғ%-”” THEN RETURN 
BUTTON 5,0 
gotresource$ = false% 
IF ForkOpen% THEN 
GOSUB CleanItUp 
ForkOpen%=false% 
END IF 
PtrTest 
GOSUB ReadFork 
Tag&-PEEKLCFFsynthPtr&*6) '"HCOM^ 
IF Тадё= 12123707656 THEN BEEP:RETURN ‘compressed 
BUTTON 5,1 
RETURN 


openResF ile: 

F$=FILES$C 1, “SFILSTAK’): IF Ғ%-”” THEN RETURN 
BUTTON 5,0 

PtrTest 

in$-0:top3-0:linenum$-0:resid$-0 

GOSUB CountResources 

GOSUB ClearBuffer 

RETURN 


Quit: 

IF ForkOpen% THEN GOSUB CleanItUp 
PtrTest 

DisposeScroll S& 

WINDOW CLOSE 2 

END 


MenSelect: 
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Menu! tem%=MENUC@) 

IF MenuItem% <> 1 THEN RETURN 
MenuCho ice%=MENUC 1) 

MENU 


ON MenuChoice% GOSUB openDataF ile, openResFile,Drawgraph, Quit 


RETURN 


writefork: 

IF gotresource$ THEN GOSUB LoadResource 

POKEW FFsynthPtr&,@ “@ for ffmode 

POKEL FFsynthPtr&*2,count& 'sizing value 
Param&=VARPTRCParamb lock%(@ )) 

POKE Param&*27,0 'reset permission 

POKEW Param&*24,&HFFFC “Sound Driver refnum 
POKEL Parem&*36,lfd& ‘length to write 

POKEW Parem&k*44,0 ' joPosMode 

POKEL Param&*46,0 ^ ioPosOffSet 

POKEL Param&+32,FFsynthPtr& ‘address of synthrec 
ToolBox "R^,RITES,Reg&C0), (Param&) ' call Write 
RETURN 


ReadFork : 
GOSUB ClearBuffer 
B2PStr F$,6$ 
Param&=VARPTR(Paramb 1lock%(8)) 
POKEL Param&+ 18,SADD(G$) ‘address of filename 
POKE Param&+27, 1 ‘read only 
ToolBox “R%, Ohpen%,Reg&(8), (Param&) ‘call .Open 
ToolBox “R”,GetEOF%,Reg&(8), CParam&) ‘call _GetEOF 
Param&=VARPTR(Paramb 1ock%(@)) 
1f d&=PEEKL(Param&+28) ‘file length 
IF 1fd& =@ THEN ‘No data 

ToolBox "R^",Klose$,Reg&C2), (Param&) 

BEEP : RETURN 
END IF 
бі2%-1Ға%%6 “6 butes for mode and count 
GOSUB GetPointer 
Paramk=VARPTR(Paramblock%(@)) 
POKEL Paramk+36,1fdk ‘number of bytes to read 
POKEL Param&+32,FFsynthPtr&+6 ‘block address 
POKEW Param&*44,1 'ioPosMode read from start of file 
ToolBox *R”,Dread%,Reg&(@), (Param&) ‘call Read 
ToolBox “R”,Klose%,Reg&(2), (Param&) ‘call -Close 
RETURN 


GetPointer : 
‘Get block of Siz& bytes and 
‘return address in FFsynthPtr& 


ToolBox “R“,NewPtr$,Regk(0),,,(Sizk) ‘call _NewPointer 


GotPointer%=trueZ% 
FF synthP tr&=Reg& (8 ) 
RETURN 


LoadResource: 

IF resid%=id%C1linenum%) THEN RETURN 
PtrTest 

‘Get the resource 

GetRes ref%, type$, іс%СТіпепит%),һ% 
res id%=i1d%8C1 inenum%) 

HLock h& 

GetHandleSize h&, 1fd& 

Sizk=1f d& 

GOSUB GetPointer 

‘coerce pointer 

ResH&=PEEKL Ch&) 

BlockMove ResH&, FFsynthPtr&, 517% 
Hunlock h& 

ReleaseRes h& 

RETURN 


CountResources: 
IF ForkOpen® THEN GOSUB Clean! tUp:ForkOpen%=false% 
PtrTest 


CountRes type$,num$ ‘number in System 
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ToolBox “WQ”,&H997,F$,ref% 'openresfile 
ForkOpen%=true% 

updateresfile ref% 

CountRes type$,num 1% 

num 18=num 1$-num$ 'number of type snd 
GOSUB GetResources 

RETURN 


GetResources: 
‘set ResLoad to false 
POKEW &HAD5E,@ ‘comment out for interpreter 
FOR ind%=1 TO пип1% 
GetIndRes type$, ind%, h& 
GetResInfo h&, id%C іла), type$, nam$ 
ReleaseRes h& 
PHS$C ind%)=nam$+” - “+STR$Cid%(ind%$)) 
NEXT ind$ 
'set ResLoad to true 
POKEW &HA5E,-1 “comment out for interpreter 
gotresource%=true% 
ActiveScroll Sk 
RETURN 


ClearBuffer: 
Param&=VARPTRCParamb lock%(@ )) 

FOR 1=0 TO 79: POKE Param&+I,@: NEXT I 
RETURN 


CleanItUp: 

CloseResf ile ref% 

InactiveScroll 5% 

in$-0: top$-0:linenum$-0:resid$-0:num12-0 
RETURN 


Drawgraph: 
DIALOG STOP :MENU OFF 
WINDOW 3,"^,(0,20)-CSwidth, Sheight),3 
MOVETO 0,0 
inc=1fd&\Swidth 
x02-0:9403-0:98-0:x2-0 
FOR I=1 TO 1fd& STEP inc 
LINETO х0%,,% 
ys -PEEKCFFsynthPtr&* CI?) 
y$2(128-92)*128 “Invert it 
PSET (x%,y%) 
xOZ=x% 
x%=x%+1 
NEXT I 
TEXTFONT 0 
MOVETO 180,300 
DrewText “Click Mouse to Continue" 
TEXTFONT 1 
WHILE MOUSEC2 )=0 : WEND 
WINDOW CLOSE 3 


WINDOW 2 
DIALOG ON:MENU ON 
RETURN 


SUB hittest STATIC 
SHARED scr&(),pt8C),num 1%, 1 inenum%, gotresource% 
in$-0 
IF NOT gotresource% THEN EXIT SUB 
IF MOUSEC@)=1 THEN 
GetMouse pt%(1) 
PtInRect pt%(1),scr%(0),in% 
IF ing THEN 
found 
END IF 
IF linenum$ 9 AND linenum%<=num 1% THEN 
State%=1 
ELSE 
state%=0 
END IF 
BUTTON 5,state% 
refresh 
END IF 
END SUB 


SUB found STATIC 

SHARED linenum%,num 1%, top%, pt%C),scr%C) 
linenum%=top%+(pt%C 1)-scr$(0))V20 

END SUB 


SUB refresh STATIC 

SHARED scr&(),PHS$C),S&,num 1%, Tinenum$,pic$ 
PICTURE, pic$ 

top%=0 

ScrollText S&,scr$C22, PHS$ C12, top’, num 1%, Tinenum$,3 
END SUB 


SUB PtrTest STATIC 
SHARED GotPointer%, a&(),FFsynthPtr& 
DisposePtr£$-&HA2 IF 
IF GotPointer% THEN “call .DisposePointer 
CALL ToolBoxC^R^,DisposePtr£$,Reg&C2), CFFsynthPtr&)) 
GotPointer$-0 
END IF 


END SUB 


My thanks to Jim Reekes, whose Sound Manager document 
cleared up a lot of muddy mental audio, and to Michelle and all 
the helpful MicroSoft folks on the GEnie MicroSoft Roundtable, 
who steered me in the right direction with some of the ToolBox 


syntax. - 
boa! 


citt 
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Basic School 
Help for HELP Software 


In spite of the fact that Apple has referred to the Macintosh 
as the computer for “the rest of us”, there are some people that still 
have trouble with computers of any kind, even the Macintosh. I 
think that Macintosh users sometimes look for complexity that is 
not there. So... there are many training courses, classes, etc. 
which may be taken to console those that may not feel comfort- 
able with the application or system environment they are work- 
ing with. 

Many commercial application programs have developed 
help systems which allow the user to access on-line documenta- 
tion of the application. The About... menu item (in the Apple 
menu) is typically the place to go to find some kind of help 
information. Users look for and expect consistency as they 
divide their time across several applications. This consistent 
atmosphere is why Macintosh users tend to use more different 
software applications than other computer users. On other 
systems users select a group of 3-4 applications and learn them 
well, but don't usually pick up other applications because of the 
time it takes to learn the new program's layout and how to get it 
to work. With the Macintosh, the consistent placement of the 
menus in the standard order (Apple Menu, File Menu, Edit Menu, 
etc.) helps to reduce the learning curve of new applications. 

Even with this consistency, users sometimes don't have the 
manual handy or can't quite remember everything that the 
application does. This is the purpose of the on-line documenta- 
tion. Help Software has recognized the need for a consistent help 
system. They have devised a system which developers may use 
to create on-line documentation quickly and easy for the user to 
use. Zedcor uses this help system to support on-line help for the 
ZBasic compiler. By typing HELP or accessing the About 
ZBasic™ dialog, the HELP DA is accessed and the ZBasic Help 
file is opened. Applications may access the HELP DA directly 
and request that specific messages be displayed in the HELP DA 
window. These are referred to as context sensitive or extended 
alerts by the HELP system. 

I'm sure you can see the benefits of having an on-line 
documentation system as part of your application. For example, 
the user can type cmd-? or hit the help button (on the extended 
keyboard) and then click or select some object or control in the 
current application and the help system will provide a help 
message specific to the object selected. This is the type of system 
that MS Word and some other Microsoft products have imple- 
mented. But with HELP Software's DA, you don't have to write 
the on-line help system, it's already written for you. 

Itisthe purpose of this column to introduce you to the HELP 
Software Desktop Help system and demonstrate a way to access 
context sensitive help messages from within your ZBasic appli- 
cation. Typically this involves more than just opening up the 
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Help DA. Under Multifinder, DAs load via the DA Handler 
unless the option key is held down when the DA is selected. For 
context sensitive help or extended alert messages, the application 
program needs to pass the message numberto the Help DA so that 
the desired message can be displayed. 

The LS Pascal code is divided into two projects. The Help 
project calls the Help DA with the option key pressed. The 
ContextHelp project calls the Help DA with the option key 
pressed and receives a integer message number which is passed 
from the calling application. Both projects are similar except for 
the message being passed. This code originated from the C 
example that Help Software provides with the Desktop Help 
system. The major difference is that the C code is a function 
instead of a procedure. I changed to a procedure because ZBasic 
doesn't provide an easy way to call a function. The CALL 
statement is meant for calling machine language or procedures 
from Pascal or C. Sinceit was tricky to getthe return (error) value 
from the function, I decided to ignore the error and change to a 
procedure. The error flag would only be used to tell the user that 
the help system was not found or the help data file could not be 
loaded. An easier method may have been to rewrite the code to 
beexecuted directly in ZBasic. Due to time constraints I have not 
been able to try that yet; ГЇЇ leave that to you. 

Since DAs don't load into the application space when 
Multifinder is active, the option key press is simulated. To do this 
the variable theKeyMap is used to pointed to the location $178 
where the key map offset to the option key is located. Modifier 
keys themselves do not generate keyboard events (see Inside 
Macintosh, I-246). The Help Software programmer followed the 
GetKey procedure with TMON and found the “master KeyMap" 
(theKeyMap). He decided to simulate an Option key press by 
putting there he same thing that pressing and holding the key 
would. The location of the option key at $178 is not documented 
anywhere, but works on all ROMS from the 128K Mac thru the 
Plus, SE, II, IIx, and SE/30. If Apple doesn't change the key 
mapping then there shouldn't be any problem. One thing to 
remember is that if you press the option key this way, be sure to 
unpress the option key by changing theKeyMap back. The 
statement: 


LongPu(theKeyMap)^ :zBitOr(LongPtr(theKeyMap)^, 4); 
presses the option key and: 

LongPu(theKeyMap)^ := 0; 

releases the option key. 


The help file is created with the Desktop Help system with 
the Help Editor. This file should be created after the application 
has been completely written, though may be updated and modi- 
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fied with the Help Editor throughout the entire development 
process. The file type of the help file should be set (with ResEdit) 
to the name of the creator of your application so that the help file 
which “belongs” to the application. DeskTop Help costs about 
$395 and allows you to edit your own on-line documentation files 
for any or all applications you desire (even commercial ones). To 
distribute the Help DA you pay a yearly license of $150 after the 
first year. The Help Editor should never be distributed, but can 
be purchased by anyone by buying the complete Desktop Help 
package. 

The see how the context sensitive help works in the sample 
ZBasic program, press the cmd-? key to change the cursor to the 
“help mode”. The program will then respond to menu selections 
and call a specific message corresponding to the message set up 
in the help file. The help key or the About... menu item will also 
select the help DA (with the option key pressed). If Multifinder 
is never used, the Help DA may be loaded directly without calling 
the Pascal procedure by using the OPENDESKACC function. 

TheZBasic program loads the Pascal code into memory with 
the GETRESOURCE function. Next the code is locked in 
memory (so it won't move on us) and the ZBasic CALL state- 
ment executes the code. We can execute the code resource 
directly because LightSpeed Pascal puts a branch to the actual 
code at the beginning of the code header. After executing the 
code, the code is unlocked and the handle is released to free up 
memory. 

These routines may be used with Pascal programs and 
BASIC withouta lot of time and effort. The whole idea is to save 
time and provide a consistent way for the user to access on-line 
documentation or help. 

Desktop Help is available from Help Software, 10659A 
Maplewood Road, Cupertino, Calif. 95014, tel. 408-257-3815. 
NOT COPY PROTECTED! 


( all Help.Help file 


Zy 


Help, Version 2.1 
Copyright © 1986, 1988. 
Matteo, Mintzias & Schlesinger. 


_) (About Help) (<-), 


unit getHelp; 


(Procedure for Calling the Help desk accessory ) 

(for Context Sensitive Help and Extended Alert Messages) 
((Copuright ©1988 , Help Software , Inc . } 

( Modified by Dave Kelly for MacTutor, April 1989 } 

( Source code in Lightspeed Pascal 2.0 } 

( This procedure will open the Help DA } 

( Under MultiFinder , this procedure will install the Help DA 


584 


in * the } 
( application heap . } 


interface 
procedure main; 

implementation 
procedure main; 


type 
LongPtr = ^LONGINT; 
var 
error, Help: integer; ( Help is the da refnum ) 
myhandle: Handle; 
name: string, 
theKeyMap: longint; 
theKegMapPtr: LongPtr; 


begin 
theKeyMap := $178; 
Help := 0; 
name := CONCAT(CHR(0), ‘Help’); 
SetResLoad(FALSE); ( Don’t load it,) 
myhandle :- GetNamedResource( ‘DRVR’, name); 


( ...just get the handle } 


error := ResError; ( -192 = Help not available ) 
Se tResLoad( TRUE); { Reset SetResLoad } 
1f (error = noErr) then 
begin { Help is available) 


EmptyHandle(myhandle); ( Try to purge the Help DA ) 
1f muhandle = nil then 
( If handle=NIL, it’s not loaded, } 
begin 
ResrvMem(SizeResource(myhandle)); 
( ...reserve memory for it ) 
error :- MemError; ( -108 = Not enough room in heap ) 
end; 
if error = noErr then (allgo...)} 
begin 
LongPtr(theKeyMap)* := BitOrCLongPtr(theKeyMap)*, 4); 
( Required to work properly with MultiFinder } 
( Press the Option key } 
Help := OpenDeskAcc(name); ( Open the Help DA } 
if (Help < Ø) and (Help = (WindowPeek 
(FrontWindow)*.windowKind)) then ( If the Help DA open ) 


begin 
end ( end if Is the Help DA open } 
else 
begin 
error := 1; 


( Let the caller know that the Help DA was not opened } 
LongPtrCtheKeyMap)^ := Ø; 
( Release the Option key } 
end; 
end 
else 
begin 
( Display an Alert : 
end 
end (Help is Available } 
else 
begin 
( Display an Alert : Help DA not available } 
end; ( End No Help Available) 
(of Help procedure ) 


Not enough memory to open Help DA ) 


end; 
end. 


unit getContextHelp; 

(Procedure for Calling the Help desk accessory ) 

(for Context Sensitive Help and Extended Alert Messages) 
((Copyright 61988 , Help Software , Inc . ) 

( Modif ied by Dave Kelly for MacTutor, April 1989 ) 

( Source code in Lightspeed Pascal 2.0 ) 
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error := 1; 


— === m——— ( Let the caller know that the Help DA was not opened ) 
= : : - LongPtr( theKeyMap)* := Ø; 
Options File (b build order) Size (Release the Option key ) 
DRVRRuntime lib end; 
Interface lib Dt 
else 
D[N] V R Helpp begin 
( Display an Alert : Not enough memory to open Help DA ) 
end 
end (Help is Available ) 
else 
( This procedure will open the Help DA and pass it the number) begin | 
(of the Help message to be displayed . ) { Display an Alert : Help DA not available ) 
( Under MultiFinder , this procedure will install the Help DA end; ( End No Help Available) 
in * the application heap . } { main:=error; for function} 
end; (of GetContextHelp ( message ) procedure } 
interface end. 


procedure main (message: integer); 
( message: number of message to display ) 


=== ContextHelp. n H= 


iaplementation z : : : 
Procedura main (message: integer); Options File (by build order) Size 
type КА | DRVRRuntime .lib 0 
gae UP = "LONGINT; Inter face lib 0 
error, Help: integer; (Help is desk accessoru refnum ) D [NJ V R ContextHelp.p 0 


param: ParamBlockRec; (parameter blck for control call ) 
myhandle: Handle; 

name: string; 

theKeyMap: longint; 

theKeyMapPtr: LongPtr; 


begin ‘This program demonstrates the use of the 
theKeyMap := $178; ‘ZBasic 5.0 CALL statement when calling 
Help := 0; “a (LS) PASCAL CODE resource. 
name :- CONCATCCHRCOD, ‘Help’); 
SetResLoad(FALSE); ( Don't load it,) 701989 MacTutor 
myhandle := GetNamedResource( ‘DRVR’, name); ‘By Dave Kelly 
error := ResError; { -192 = Help not available ) 
Se tResLoad( TRUE); ( Reset SetResLoad } WINDOW OFF 
1f (error = noErr) then COORDINATE WINDOW 
begin ( Help is available) DEF MOUSE=~ 1 
EmptyHandleCmyhandle); ( Try to purge the Help DA ) MOUSE ON 
if myhandle = nil then BREAK ON 
( If handle-NIL, it’s not loaded, ) DEFSTR LONG: TR=CVIC*CODE*) 
begin DEF LEN=255 
ResrvMem(SizeResource(myhandle)); DIM B&C7) 
( ...reserve memory for it } GOSUB "Def ine Help Cursor” 
error := MemError; APPLE MENU “About Call Help” 
( -108 = Not enough room in heap ) MENU 1,0, 1, “File” 
end; MENU 1, 1, 1, “Open...” 
if error = noErr then (all go...) MENU 1,2, 1,*Close” 
begin MENU 1,3,0,%-” 
LongPtrCtheKeyMap2* := BitOr(LongPtr(theKeyMap)~, 4); | MENU 1,4, 1, "Save" 
( Required to work properly with MultiFinder ) MENU 1,5, 1, "Save Аз..* 
( Press the Option key ) MENU 1,6,0,4-% 
Help := OpenDeskAcc(name); ( Open the Help DA ) MENU 1,7, 1, “Раде Setup." 
1f (Help < 0) and (Help = MENU 1,8, 1, "Print." 
(WindowPeekCFrontWindow2^ .windowKind2) then MENU 1,9,0, *-* 
( If the Help DA open ) MENU 1, 10, 1, “Quit?” 
begin EDIT MENU 2 
param. ioCompletion := nil; Message$-0 ‘Set up string parameters 
param. ioRefNum := Help; HelpCursor$-9 
( Help is the value returned) | | 
( bu the OpenDeskAcc call ) 'Find out screen size. 
param.csCode := 5000; CALL GETWMGRPORT(WMgrPortk) 
( 5000 tells the Help DA: “This is) PortTop=PEEK WORD(WMgrPort&*8) 
(a context sensitive help call” ) PortLef t=PEEK WORDCWMgrPor t&* 10) 
рагат.с5Рагат(01 :- message; Por tBot tom=PEEK WORD CWMgrPor t&+ 12) 
( Help message to display ) PortRight=PEEK WORDCWMgrPor t&+ 14) 
17000 2 ) WINDOW 1, “Main Window", C10, 44)-CPortRight-4,PortBottom-4),5 
( asynchronous control call tells Help DA what to show ! , Main Window”, C18, 44)- CPortRight-4,Por 24), 
; end ( end if Is the Help DA open ) GET WINDOW 81, WindowPtr& 
im ON MENU GOSUB “Do MenuEvent"^ 
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ON DIALOG GOSUB “Do DialogEvent^ 

MENU ON:DIALOG ON:BREAK ON 

“Loop” 

CALL бЕТКЕҮ5(8%(0)2 

LONG IF B$(22216 AND B&(3)=-32767 
GOSUB “ChangeCursor” 

END IF 

GOTO “Loop” 


DIALOG OFF:MENU OFF 
“По MenuEvent"^ 
Menunumber=MENUC@ ) 
Menuitem=MENUC 1) 
MENU 
SELECT Menunumber 
CASE 255 
Message%=0 
GOSUB “Do Call” 
CASE 1 
GOSUB “Do File Menu” 
END SELECT 
HelpCursor$-1 
Message%=0 
GOSUB *ChangeCursor" 
RETURN 


"Оо File Menu” 
LONG IF HelpCursor$-0 
SELECT Menuitem 
CASE 1 “Open 
CASE 2 “Close 
CASE 4 “Save 
CASE5 “Save As.. 
CASE 7 ‘Page Setup.. 
DEF PAGE 
CASE 8 ‘Print... 
DEF LPRINT 
CASE 10 ‘Quit 
GOTO “Quit” 
END SELECT 
XELSE 
SELECT Menuitem 
CASE 1 ‘Open 
Message%= 1 
GOSUB “Do Call’ 
CASE 2 ‘Close 
Message%=2 
GOSUB "Do Call’ 
CASE 4 ‘Save 
Message%=4 
GOSUB “Do Call’ 
CASE 5 ‘Save As.. 
Message%=5 
GOSUB “Do Call’ 
CASE 7 ‘Page Setup.. 
Message$-7 
GOSUB “Do Call” 
CASE 8 ‘Print... 
Message$-8 
GOSUB “Do Call” 
CASE 10 “Quit 
Message%= 10 
GOSUB “Do Call” 
END SELECT 
END IF 
RETURN 


“Quit? 
END 


“По DialogEvent" 
D=DIAL0G(O):DI=DIALOGCD) 
SELECT D 

CASE 1 ‘Button 
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CASE 2 ‘Edit Field 
CASE 3 ‘Inactive Window 
CASE 4 ‘Close Box 
GOTO “Quit” 
CASE 5 ‘Window Update 
CASE 6 ‘Return Key 
CASE 7 ‘Tab Key 
CASE 8 ‘Zoom-in 
CASE 9  'Zoom-out 
CASE 10 'Shift-Tab 
CASE 11 'Clear Key 
CASE 12 'Left-Arrow 
CASE 13 'Right-Arrow 
CASE 14 'Up-Arrow 
CASE 15 'Down-Arrow 
CASE 16 ‘Event inkey$ 
IF DI=5 THEN GOSUB “Do Call” 
CASE 17 ‘Disk Insert 
END SELECT 
RETURN 


“По Call’ 
LONG IF Message%=0 
Id-500 ‘Help DA 
XELSE 
Id-501 ‘Context Sensitive Help 
END IF 
Resul t&=8 : YZ=0 
SCode&= FN GETRESOURCECT&, Id) ‘load the call into memory 
IF SCode&=8 THEN PRINT "Opps^:END'End if there is no call to 
call 
YZ=FN HLOCKCSCode&) “ Lock a Relocatable Memory Block 
ActualCode&=PEEK LONG CSCode&) 
LONG IF Message$-0 
CALL ActualCode& “Call the Help procedure 
XELSE 
CALL ActualCode&(Message%) ‘Call the Context Sensitive Help 
function 
END IF 
CALL RELEASERESOURCE (SCode& ) 
YZ=FN HUNLOCK(SCode&) “Unlock a “Locked” Handle 
Y%=FN DISPOSHANDLECSCode&) ‘Dispose of Memory block pointed 


to by a ‘Handle 
Message$-9 ‘Set up string parameters 
RETURN 


*Def ine Help Cursor" 

DIM А%(40) 

A8C0)-&H0000 : ABC 1)-&H3F80 : A$(2)-&HTFC2 : AS C3)-&HO60CO 
A$C42-&H60C0 : A$(5)-&HOOCO : A$(6)-&H0 108 : АСТ 2-6 H0380 
A$C8)-&H0700 : A$(9 )-&HOEOQ : ABC 10 )-&HOCO : ABC 1127 &HOCO0 
ASC 12)=6Н0000 : AZ C 132-&HOC00 : ABC 14 =RHBCHO : ABC 15 )=6Н0000 
ASC 160-2 &H3F 80 : ABC 17 )= НТЕС? : ABC 18) -&HFFEO : AS C 19)-&HFFEO 
A$C200-&HF 1Е0:А%(2 10:&HF 1Е0 : ABC22=&HBSED :A$(23)-& H0 7CO 
A$C24)z&HOF80 :A$(25)-&H IF OO :A$(262-&H 1Е00 :A$ (27 )-&H 1Е00 
A$(28)-&H 1EØØ :A$(29)-&H 1Е00 : ABC 30)- &H 1Е00 : AS (3 1 =H 1E20 
A8(32)-&H0004 :A$(33)-&H0002 

He ]pCursor%=8 

RETURN 


*ChengeCursor ^ 
LONG IF HelpCursor%=8 
CALL SETCURSORCASC2)) 
CALL SHOWCURSOR 
HelpCursor$-1 
XELSE 
CURSOR=8 
HelpCursor$-9 
END IF 
WHILE B$(22216 AND В%С32--32767 
CALL GETKEYSCBSCO)) 
WEND = 
RETURN peg! 


citu». 
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Basic School 


Useful Routines For ZBasic 


Hello! Are any of you tired of switching back and forth 
between versions of Basic? Although ZBasic still holds an edge 
over other Basics in the competition, there are benefits in favor 
of using other Basics from time to time. The frustrating thing 
about it is when you try to use a command, syntax, or subroutine 
with the wrong version of Basic. It’s easy to do if you switch back 
and forth very often. It’s also frustrating when your favorite 
function isn’t implemented the same (or notat all) from what you 
are used to. 

Charles Stricklin has sent in three functions which he wished 
were already implemented in ZBasic. These have been designed 
to add to your ZBasic library of routines. The GETIND- 
STRINGS function works similarly to the GETINDRESOURCE 
function in the Macintosh toolbox. This routine allows easy 
retrieval of strings stored in a ‘STR#’ resource. 

The GETRESWINDOW and GETRESMENU functions 
will get WIND and MENU resource data and interpret the 
resource to open up windows and setup menus using standard 
ZBasic statements. This is useful if you would like to use 
resources like 'real' applications do. 

The program demonstrates the use of these functions. In 
developing this and through debugging the functions I am now 
even more aware of the missing capability to include resources 
from a resource file when compiling with ZBasic. This is a 
deficiency which I would hope Zedcor has as #1 on their ‘TO DO’ 
list. Charles also listed this problem as high priority and wrote 
a short routine as a work around for the meantime: 


debugging = -1: ‘Cor TRUE if defined previously TRUE during 
development. 


*OpenResourceFork^ :'used in development only 
LONG IF debugging : "we're still writing this 
CALL PARAMTEXTC^Do you want to use a specific 
resource”, "file?^, ##“ +”) 
myAnswer = FN CAUTIONALERTC3,NIL): gets my answer from 
alert 
LONG IF myAnswer =1 71 said “YES” 
resourceF ilename$ = FILES$CI,"rsrc^, , volume) 
filename 


:'gets а 


'(created with ResEdit) 
refNum = FN OPENRESF ILECresourceF i leName$) ; ^and 
opens it's 
| ‘resource fork 
END IF :'(myAnswer = 1) 
END IF :"Cdebugging) 


RETURN :’C“QpenResourceFork” ) 
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Вахё Dave Kelly 
w ! MacTutor Editorial Board 
Volume 5, Number 7 


Other items on the ZBasic “Wish List” include: 

(to be fixed): 

° The “Save Changes?” alert should only be called after the 

user has actually made changes to an existing document... espe- 
cially not right after launching ZBasic itself when 
opening an existing document. 

° ZBasic doesn’t run reliably under MultiFinder. After 
several passes editing and running, ZBasic aborts even 
with 2.5+ Meg memory allocated to ZBasic. I’ve never 
had this happen when not running Multifinder. I sug- 
gest that Multifinder be turned off when editing and 
debugging ZBasic programs. 


(to be improved): 

e The ‘Find’ command is somewhat useless without a 
‘Change’ command. 

e The editor, even with the vast improvements over 
earlier versions, is still clumsy in several (many) areas. 

e The default tab settings are a nuisance. This should be 
user definable. 

° Editing would be much easier if more than one edit 
window (different files too) could be open at the same 
time. 

° Lower the price. The ToolBox Editor should have been 
part of the package to begin with. The Program Genera- 
tor is useful if you don’t already have your own custom 
BASIC shell defined. | 


On the plus side, ZBasic is still the fastest and has been very 
reliable since version 5.0 was released. If the price were still 
under $100, it would be a bargain. At the present time Light- 
Speed Pascal or C is a much better bargain when compared with 
ZBasic. 

I'm sure that there are others routines which MacTutor 
readers have been using which would be useful to others. Send 
your routines to me via MacTutor and see your name in print! 
Thanks Charles! 


‘ This program contains 3 new subroutines which 
“пау be used with the ZBasic Program Generator. 
‘ @1989 MacTutor 

* Subroutines by Charles Stricklin, modified by Dave Kelly 


‹'ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


4 О CONFIGURATION O 
ОООО ОООО 


Default Variable Туре: Integer 
Convert to Upper Саѕе :Үеѕ 
Space Req.After Key Words: Yes 
Array Base 1:No 
Bundle Bit:Yes 


% 3 оъ аз з % 
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е 
$929292929292922992920999222292222922929229922929299222092922222222292929992929 
r O SET UP VARIABLES o 
'ЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖ 
WINDOW OFF:COORDINATE WINDOW:DEF MOUSE=-1:WIDTH -2 

DIM T,L,B,R,MY, MX? REQUIRED FOR TOOL BOX CALLS 
f 


WND= 1:GOSUB”BUILD WINDOW” 

GOSUB “BUILD MENU” 

GOTO"EVENT QUEUE” 
(XXXXXXKXXXXXKXXXKXK1XXKXKXKXXXXKXXKXXXXKXXKIXXXXXXXKXXXXXKXXXXXXKXK 
f o THE QUEUE О 
'ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
“EVENT QUEUE” 

ON DIALOG 60508 “HANDLE DIALOG^:DIALOG ON 

ON BREAK GOSUB “HANDLE BREAK” :BREAK ON 

ON MOUSE GOSUB "HANDLE MOUSE” :MOUSE ON 

ON MENU GOSUB “Handle Menu” :MENU ON 


“LOOP” 
GOTO^LOOP^ 


DIALOG OFF:BREAK OFF:MOUSE OFF 
* ХХХХХЖХЖХЖХЖХЖХХХХХХХХЖЖХХХХХХХХХХХХХХЖХХХХХХХХХЖХЖХЖХЖХХХХЖХХХХХЖЖЖ 


j o DIALOG ROUTINES O 
ОООО ОООО ОООО ООК 


“HANDLE DIALOG” 

ACT=DIALOG(B):REF=DIALOGCACT) 

IF ACT=3 THEN WINDOW REF :RETURN 

IF ACT=4 THEN GOSUB*CAPTURE”: WINDOW CLOSE REF : ЕМО 
IF ACT=5 THEN “FORMAT WINDOW" 

IF ACT=11 THEN EDIT FIELD REF, "^ 


LONG IF WINDOWCØ)=1 


END IF 

RETURN 
СКОКА 
r O BREAK ROUTINE O 


'ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


“HANDLE BREAK” 


END 
СКК 
( 0 MOUSE ROUTINES 0 


СКОКА 
“HANDLE MOUSE” 


MACT=MOUSE(@): MX=MOUSE( 1): MY=MOUSE (2) 


RETURN 

“Handle Menu” 

MenuNumber=MENUC@ ) 

Menu i tem=MENUC 1) 

MENU 

IF MenuNumber=1 AND Menuitem=12 THEN END 
RETURN 


'GETINDSTRING$ function By Charles Stricklin 
‘Modified by Dave Kelly for MacTutor, May, 1989 


'This function is identical to the procedure GetIndString 
‘which is not in ROM and not supported by ZBasic. It reads 
‘a String from a string list and returns a copy of it in the 
‘variable the String$. If the string list doesn’t exist of 
the 

'index is out of range an empty string is returned. 


' stringListID is the resource ID of the string list; it's 
resource type is ‘STR®’. 

‘ stringIndex is the index of the desired string within the 
list. 
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LONG FN GETINDSTRING$(CStringListID, StringIndex) 
TheStr ing$- "^ 
Offset-0 
ҒА( 5Е-0 
MyHandle&sFN GETRESOURCECCVIC*STRS^)5,StringListID) 
LONG IF FN RESERROR-FALSE 
MyPointer&=USR 3CMyHandle&) 
NumberOfStrings-PEEK WORDC(MyPointer&) 
LONG IF CStringIndex»9) AND CStringIndex <= Number- 
OfStrings) 
LONG IF StringIndex 1 
FOR ThisString=1 TO StringIndex-1 


LengthOf ThisStr ing-PEEKCMgPo inter&*2*0f f set) 
Of fset=0f fsettLengthOf ThisString*1 
NEXT 
END IF 
LengthOf DesiredString-PEEKCMgPointer&*2*0ffset) 
FOR Character=1 TO LengthOfDesiredString 


TheS tr ing$=TheS tr ing$* CHR$CPEEKCMgPo inter&*2*0f f set*Character)) 
NEXT 


END IF 
MyHandle&=USR 7(MyPointer&) 
CALL DETACHRESOURCE (MyHand1e& ) 
END IF 
END FN» TheString$ 


'GETRESMENU function By Charles Stricklin 

'Modif ied by Dave Kelly for MacTutor, May, 1989 

‘This function creates a ZBasic menu from a MENU resource. 
‘The result given is boolean; true if the task is accom- 
plished, 

‘false if there's a problem (the resource doesn’t exist, etc.) 


‘ resourceID is resource ID of the menu resource to be used. 
' menuNumber is the ZBasic number of the menu to be created. 


LONG FN GETRESMENUCResourceID, MenuNumber) 
DEFSTR LONG 
Done=0 
FALSE=0 
MenuBlkSize=14 
Title$=”” 
MuHandlek=FN СбЕТКЕЗОЦЕСЕССУІС”МЕМ/”2,Ревохгсе10) 
LONG IF FN RESERROR=FALSE 
MyPointer&=USR 3C(MyHendle&) 
EnableF lags&=PEEK LONGCMyPointer&+ 10) 
State=VALCMID$CBIN$CEnableF lags&), 32, 12) 
LengthT it le=PEEK CMyPointer&+MenuBlkSize) 
FOR Character=1 TO LengthTitle 
Title$=Title$+CHR$ (PEEK (MyPointer&+MenuB1lkSize+Character )) 
NEXT 
MENU MenuNumber ,@,State, Title$ 
Of fset&=MenuBlkSizetLengthTitlet! 
DO 
MenuItem-MenuItem*1:Title$-"" 
LengthTitlesPEEKCMyPointer&*Of f set&) 
FOR Character=1 TO LengthTitle 
Title$=Title$+CHR$CPEEK (MyPointer&+0f f set&*Character 2) 
NEXT 
Of fset&=Of fset&+LengthTitlet+1 
IconNumber&-PEEK CMyPo inter&*Of fset& ) 
IF IconNumber& THEN 
Titlef-Title$*"^ "*RIGHTÉ$CSTRÉCIConNumber&), 1) 
CommandKey-PEEK CMyPo inter&*Of f set&* 1) 
IF CommandKey THEN Title$zTitle$*"/ 
**CHR$CCommandKey) 
MarkChar = PEEK(MyPointer&+0f fset&+2) 
IF MarkChar THEN Title$=Title$+*!“+CHR§$(MarkChar ) 
CharacterSty]le=PEEK CMyPointer&+0f fset&+3) 
IF FN BITTSTCCharacterStyle,@) THEN 
Title$=Title$+*<B’ 
IF FN BITTSTCCharacterStyle, 1) THEN 
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Title$-Title$*^«I^ 
IF FN BITTSTCCharacterStyle,2) THEN 
Title$-Title$*^«U^ 
IF FN BITTSTCCharacterStyle,3) THEN 
Title$-Title$*^«0^ 
IF FN BITTSTCCharacterStyle,4) THEN 
Title$-Title$*^«S^ 
State-VALCMID$CBIN$CEnableF lags&), 32-MenuItem, 1)) 
Of fset&=0f fset&+4 
MENU MenuNumber, MenuItem, State, Title$ 
UNTIL PEEKCMyPointer&+0f fset& J=FALSE 
Done=- 1 
END IF 
MyHandle&-USR 7CMyPointer’&) 
CALL DETACHRESOURCE CMyHand1e& ) 
END FN=Done 


‘GETRESWINDOW function By Charles Strick] in 

‘Modified by Dave Kelly for MacTutor, May, 1989 

‘This function creates a ZBasic window from a window template 
'resource. Result given is boolean;true if task is accom- 
plished, 

'false if there's a problem ( resource doesn't exist, etc.) 

‘ resourceID is the resource ID of window template to be used. 
‘ windowNumber is ZBasic number of the window to be created. 

‘ modal is boolean. 


LONG FN GETRESWINDOWCResourceID, WindowNumber, Modal) 
Done=0 
Title$-*" 
FALSE-0 
MyHandle&-FN GETRESOURCECCVIC “WIND” ), ResourceID) 
LONG IF FN RESERROR=FALSE 
MyPointer&=USR 3(MuHandle&) 
Y1=PEEK WORDCMyPointer&) 
X1-PEEK WORDCMyPointer&+2) 
Ү2=РЕЕК МОВО СМуРоіпіег& +4) 
X2=PEEK WORDCMyPointer&+6) 
Type=PEEK WORDCMyPointer&+8 )+ 1 
HasClose=PEEK WORDCMgPo inter&* 12) 
LengthOf Title-PEEKCMyPointer&* 18) 
FOR Character=1 TO LengthOfTitle 
Title$=Title$+CHR$ (PEEK (MyPointer&+ 18* Character 2) 
NEXT 
IF Tupe=13 THEN Type=9: ‘ZBasic doesn’t support 
ZoomNoGrow 
IF HasClose-FALSE THEN Туре-Туре%256 
IF Modal THEN Туре--Туре 
WINDOW WindowNumber, Title$,CX1, Y 12- CX2, Y22, Type 
Done=- 1 
END IF 
MyHandle&=USR 7(MgPointer&) 
CALL DETACHRESOURCE (MyHand1e& ) 
END FN=Done 
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‹ЖЖЖЖХЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
' O WINDOW ROUTINES o 
‹'ЖЖЖЖЖЖЖХЖХЖХЖЖЖЖЖЖАЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
"BUILD WINDOW’ 

IF WND=1 THEN Result-FN GETRESWINDOWC 1, 1,0) 

GOSUB^BUILD EDITS^:GOSUB^FILL EDITS^:GOSUB "FORMAT WINDOW” 


RETURN 
(XXXXXXXXXXXXXX1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKX 
í О MENU ROUTINES О 


'ЖЖЖЖЖАЖЖЖАЖХЖЖХЖЖЖЖАЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


“BUILD MENU” 
Result=FN GETRESMENUC 1202, 1) 


RETURN 
КОККО ОККА 
f O PUT GRAPHICS & TEXT IN WINDOW O 


CXOOOOOoIOIOOKOKOE ORO GO OO XOoIoXooKOOoKoXooororororororororororoorororooororopeoroooeoocex 


"FORMAT WINDOW^ 
CALL PENNORMAL 


LONG IF WINDOWCO)-1 

PrintString$-FN GETINDSTRING$(31618, 1) 
LOCATE 1, 1:PRINT PrintString$ 
PrintString$-FN GETINDSTRING$(31618, 2) 
LOCATE 4,2:PRINT PrintString$ 

END IF 


CALL PENNORMAL: RETURN 


'ЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


í O CREATE EDIT FIELDS AND BUTTONS о 


,. ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


“BUILD EDITS” 


TEXT ,,0,0 

LONG IF WINDOW(0)=1 

END IF 

RETURN 
'ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
; O FILL EDIT FIELDS AND SET BUTTONS o 


'ЖЖЖЖЖЖЖЖХЖЖЖХЖХЖЖЖЖХЖХЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖ 


“FILL EDITS” 


LONG IF WINDOW(O)=1 
END IF 


RETURN 
‹ЖЖЖАЖЖАЖАЖЖЖХЖАЖЖАЖЖХЖЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


4 0 CAPTURE EDIT FIELD STRINGS & READ BUTTONS 0 


(XXXXXXX5XXXXXXXXXXXXXXXXX1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKXX 
“CAPTURE” 


LONG IF WINDOW(O)=1 
END IF = 


l: 
RETURN E 
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HyperChat™ 


XCMD Cookbook: HyperAppleTalk "sPertar4 


HyperCard Networking 
One of the areas where XCMDs can dramatically alter the 
capabilities of HyperCard is networking. HyperCard 1.2 intro- 
duced the concept of shared stacks by implementing an interface 
to AppleShare. Unfortunately, too many people have come to 
believe that AppleShare is all the networking that you need in 
HyperCard or in any other application on the Macintosh. 


Networking can offer a lot more than simple file access to the 
user. Imagine sending messages or data between stacks interac- 
tively. While I was still at Apple, we implemented two stacks that 
better explain this concept. Imagine that one Mac on the network 
acted as the stock exchange. Each successive stack that logged 
in becomes a stock broker and can immediately begin buying and 
selling stocks and competing against other brokers on the net- 
work. This was a fun little project that took on a wonderful new 
dimension when we added the network interface. There is no 
truth to the rumor that we began beta testing this stack on October 
19, 1987! 

A second stack that we wrote provided the capability of an 
interactive chalkboard. Everybody who logs in can see the 
Chalkboard as well as pick a paint tool and actually draw some- 
thing on the board. Every other user would see these changes. An 
interesting exercise in cooperative work area applications. 


HyperAppleTalk 

The code that I used to implement these sample stacks is a set 
of XCMDs called “HyperAppleTalk”. These XCMDs imple- 
mented the AppleTalk Transaction Protocol (ATP) and the Name 
Binding Protocol (NBP). ATP is a network protocol that imple- 
ments the server/client model. One entity on the network acts as 
an information provider or server while subsequent systems act 
as information requestors or clients. Although this is a very 
flexible model, the particular implementation of ATP is a little 
too limiting. Client requests must be less the 578 bytes in length 
and server responses must be less than 4624 bytes. If a client 
made a request to the user for a file that is greater than 4600 bytes, 
the ATP protocol would need help from another protocol layered 
on top of ATP. I chose not to implement this protocol because 
ATP as it stands is more than adequate for sharing messages 
between stacks. You can obtain a copy of these XCMDs, written 
in MPW C, from the Apple Programmers and Developers Asso- 
ciation (АРПА). 


The second protocol that I implemented in HyperAppleTalk 
is the Name Binding Protocol. This is the mechanism by which 


user names are associated with network addresses on AppleTalk. 
The name binding protocol allows you toregister a name with the 


€ The Best of MacTutor, Vol. 5 


Donald Koscheka 

Arthur Young & Company 
MacTutor Contributing Editor 
Volume 5, Number 1 


54 


network. This is ап important feature since network addresses 
tendtoresemble phone numbers. Imaginehow much trouble you 
would have using the phone if you knew only a party's number 
and not their name! 

Over the next several months I will be providing you with 
network access in HyperCard. This month I will introduce the 
concept of “connecting” to the network, that is, establishing the 
address and record structures required to maintain communica- 
tion with the network. Next month, I will provide a complete set 
of routines for access to the Name Binding Protocol. The third 
installment will feature an important new protocol, the Ap- 
pleTalk Data Stream Protocol. Finally, we'll add some embel- 
lishments such as access to multiple networks across bridges and 
file transfer across the network. The result will be complete set 
of protocols that will allow you to interactively send messages, 
data and even entire files between stacks running on different 
systems. 


“Connecting” to the Network 
To help us get started, we need to examine network basics. 
Because network programming carries the aura of being diffi- 
cult, I will keep this introduction simple. You can obtain more 
information from Inside Macintosh, Inside AppleTalk or from 
back issues of MacTutor (April '87, Vol. 3 No. 4) which is where 
I first learned how to program for the network. 


A network consists of a number of entities that are connected 
by some common transport mechanism. Foremost of us, this 
transport mechanism is LocalTalk. A node is any device that can 
be connected to the network and share information with other 
devices. For sake of illustration, think of each device on the 
network as a single node. 


The set of software protocols that control the traffic and 
communications on the network is called *AppleTalk". These 
protocols are quite independent of the cabling between entities 
whichis why Apple wentto such pains to divorce LocalTalk from 
AppleTalk. This separation pays dividends to the programmer. 
We can think of AppleTalk as a software mechanism and not 
worry a whit about what wires are connected. 


AppleTalk functions at a variety of levels. At the lowest 
level, AppleTalk coordinates the transmission and reception of 
discrete packets of information between entities. To ensure that 
two entities don't “hog up the wire" each communication is sent 
as packets of about 600 bytes of information. A 6K file will 
require about 10 packets to be sent in its entirety. We call the 
complete communication of all packets a transaction. The 
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completion of a transaction is guaranteed for you by AppleTalk 
via the Dynamic DataLink Protocol (DDP), and we need not 
concern ourselves with it at this time (there are lower-level 
protocols than DDP, but we don’t need to know them to do 
serious programming on the network. Think of the lower layers 
as the network’s “assembly language”). 

Nodes address each other on the network by their network 
addresses. As we said, Network Addresses are similar to phone 
numbers. If you know the network address of any entity, youcan 
communicate with that entity. The network address consists of 
three objects: the network number, the node and the socket. For 
now, we П assume thatall entities are on the same network so that 
the network number is always 0 (we’ll relax this constraint later 
when we introduce the concept of internet addressing with the 
Zone Information Protocol). The second part of the address is the 
node id which uniquely identifies an entity within a given 
network. 

The most important concept in the network address is the 
conceptof a socket. A network address is a 16-bit object (a pascal 
INTEGER) that remains constant for as long as that network 
remains active. The node id is an 8-byte entity that remains valid 
for as long as an given node in the network stays up. Sockets, 
unlike network and node id’s, come and go as needed. Sockets 
are associated with individual transactions on the network and 
provide a vital way for the network to properly route transactions 
between nodes on the network. 


Socket Flavors 

For our purposes, sockets come in two flavors, listening 
sockets and transaction sockets. Each node on the network needs 
at least one “semi-permanent” listening socket whose sole job is 
toreact to incoming requests from other nodes. Listening sockets 
are like the “ringer” on your telephone. They don’t do much more 
than let you know that someone is trying to get a hold of you. 
Listening sockets are said to be semi-permanent because they are 
assigned to a single node for as long as that node remains 
connected to the appropriate protocol. In ATP, a listening socket 
is equivalent to a server. In ADSP, as we shall see, a listening 
socket is also called a connection listener. 

The second class of sockets are “dynamic” sockets which I 
refer to as transaction sockets. Once a connection is established 
between any two nodes, a transaction socket is assigned to those 
two nodes for the duration of that transaction. Once the transac- 
tion is completed, the dynamic socket is returned to the “socket” 
pool. This is important because a socket is an 8-bit entity. With 
only 256 possible combinations, the need to conserve and reuse 
socket numbers becomes important. 

The neat thing about dynamic sockets is that they uniquely 
identify a given transaction. One node can easily carry on 
multiple conversations simultaneously because each conversa- 
tion is identified by its unique socket id. Dynamic sockets are 
assigned and de-assigned automatically. We won't have to 
concern ourselves with the intricate underworkings of this 
mechanism in this discussion. All we need to remember is that 
when we establish a connection with another entity on the 
network, that connection will receive a unique socket id. When 
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we “tear down" the connection, that socket will be made avail- 
able for a future connection. 


Name Calling 

Keeping track of nodes on the network by their network 
address is not particularly user friendly; it would be roughly 
similar to calling people by their social security numbers. And 
we know that’s not user friendly because only government 
agencies and the DMV would think of doing that! 

We need a way of identifying a given node on a given 
network with a particular user. In other words, we need a way of 
binding a user-selectable name with a given network address. 
This is accomplished using AppleTalk’s name binding protocol 
(NBP). To bind a name to a network address, we need both a 
name and an address. Choosing a name is a matter of taste. You 
can use the name that the user entered in the chooser, or you can 
ask the user for a name. We'll present both techniques since not 
every user types a name in the chooser dialog. Next we'll need 
to know what address to bind that name to. We can't bind a name 
toa dynamically assigned address for an obviously subtle reason. 
That is, a node can have a name, a transaction takes on the name 
of whichever node the transaction is taking place on. As far as 
why this is true, it should become obvious as you read through the 
code (i.e. it is left as an exercise for the student). 

The binding of a name to a network address can only be done 
once we establish an address for the listening socket. The 
listening socket is protocol-sensitive - we don't want to open a 
listening socket for ATP if we're going to be using ADSP as our 
communications protocol. Thus, we'll need to open up access to 
ADSP first to establish the socket address. Once we have this 
address, we can pass it to the Name Binding Protocol (NBP) 
along with a name to establish a link. We refer to the association 
of a name with a network address as an "entity". An entity is said 
to be network visible if any other entity on the network can see 
the address of that entity. 

To gain access to the network, we first check to see if 
AppleTalk is installed with the call to MPPOpen in ADSPOpen 
(see listing 4). Next, we open up the ADSP protocol driver, 
intialize some global variables and then establish an ADSP 
listening socket. We use the setglobal callback to set the values 
of the globals "HyperADSPData and “mySocketListener”. 
These globals must be declared before they are used or you may 
find that earlier versions of HyperCard will bomb out (alas, a bug 
in HyperCard). 

We don't need to open the Name Binding Protocol (NBP) 
driver since it is automatically opened for us if AppleTalk is 
running. The XFCN NBPOpen ( see listing 5 ) initializes the 
fields in the NBPBlock record. Don't worry about what those 
fields do, they'll be the topic of next month's article. 

Listing la is a sample HyperTalk script for opening both 
ADSP and NBP. Note that if ADSP doesn’t open, there is no need 
toopen NBP; we didn't get access to the network (the most likely 
reason for this is that the ADSP driver was not installed at boot 
time). 

If ADSP opens ok, it sets the globaladspdata and mysocket- 
listener global containers. NBP will need access to the latter 
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container, while globaladspdata is used solely by our ADSP 
xcmds. Don’t worry about the individual fields in all the records 
yet, we'll cover them in sufficient detail in upcoming issues. 


The important actions to point out right now is the opening 
of the “.dsp” (aka ADSP) driver and the assigning of a listening 
Socket. Also, three globals will be used for storage. Glo- 
balNBPData stores a pointer to ош NBPBlock. Note that the 
pointer is stored as a numeric string. This is just to keep 
compatible with HyperCard's wanting to use containers to store 
strings. Similarly, GlobalADSPData stores a pointer to the 
ADSPBlock and mySocketListener stores the value of the con- 
nection listening socket (to be discussed in gory detail in an 
upcoming issue). Changing any of these values will result in the 
untimely death of your stack. Make sure your users don't have 
access to these containers. 

Listings 2-3 contain some global constant and type declara- 
tions for ADSP and NBP respectively. Again, there is a lot more 
there than I can cover in one issue of this magazine, let alone a 
single column. We will cover all of this information in more 
detail so stay tuned. 

Because we should never leave something undone in Hyper- 
Card, a pair of complementary XFCNS are provided in listings 6 
and 7. ADSPClose and NBPClose check to see that their global 
data is allocated. If not, they assume that the drivers are already 
closed and just return. Otherwise, shut down the communica- 
tions and clear out the global data. We don't actually close either 
AppleTalk or ADSP because some other application may have 
opened them after we did. This is an important exception to the 
“If you opened, you close it rule". In general, if you open an 
AppleTalk driver, you can leave it open because another appli- 
cation may already be using it. Listing 1b shows one way to 
access these XFCNs. 


on openstack 
global globalNBPData, myRegisteredType, myRegisteredName 
global globaladspData, mySocketL istener 


put adspOpen() into it 
if it is empty then 
— have access to adsp and a valid socket in 
- mySocketListener, okay to continue 
put nbpOpen() into it 
if it is not empty then 
answer "Could Not gain access to NBP^ with "OK" 
else 
answer "Welcome to AppleTalk” with “OK” 
end if 
else 
answer “ADSP Driver Not installed” with "OK" 
end if 
end openstack 


Listing la. A sample Script to Open access to the 
network 


on closeStack 
global globalNBPData, myRegisteredTgpe, myRegisteredName 
global globaladspData, mySocketListener 


put adspClose() into some_sort_of_error 


put nbpclose() into get. another. result 
end closeStack 
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Listing ib. A sample Script for closing down the 


network 


Qoocoooooooooppoooooooooooopeoeer) 
(* file: ADSPxcmd.p х) 


(* х) 

(* Interface stuff for adsp *) 
(* *) 

С --------%) 


(* Bu: Donald Koscheka *) 

(Ж Date: 18-Oct-88 х) 

(Ж ———————— X) 
(YXYXXXXXXXX1XXXXXX1XXXXX1XXXXXXXKXX) 


UNIT adspxcmd; 
INTERFACE 


USES Memtypes, QuickDraw, OSIntf, 
ToolIntf, AppleTalk, ADSP; 


CONST 

ASYNC = TRUE; 

SYNC = FALSE; 

(*** connection mode status ***) 
NOP =й; 

REQ = 1; 

ACK = 2; 

EST = 3; 


д 


NBPLSIZE = 120; 
ATPBSIZE = 578; (standard size of transaction) 


INTERVAL = 20;( default retru interval) 
RETRY = 3; ( retru count =3 (3*60=30 secs)) 
CLOSE_OK = 0; 

RECEIVING = 1; 

CLOSE.NOW = 2; 
(YXXXXXXXXXXXXXXXXXXXXXXKXXXXXXXXXXXX) 

(* The following data blocks ж) 

(% reference memoru pointers х) 

(* rather than handles. This х) 


(* is to insure that all of the *) 
(* data in the connection block *) 
(* is non-relocatable since х) 


(* ADSP runs asynchronously х) 
655155 222 2542255424222422222225 


ТҮРЕ 


LIntPtr = “LongInt; 
IntPtr = “INTEGER; 


(жжжжжжжж A connection block 
CBPtr = “Connection; 

Connection = Packed Record 
next: CBPtr; — ( pointer to next connection } 
lest: CBPtr; (pointer to last connection ) 
ccbRef: Integer; ( connection reference #  ) 
mode: Integer; ( set if connection is open ) 
adr : AddrBlock; ( address of remote end  ) 
msg : Handle; ( callback for incoming dat 


KKK KKK ERK xxx) 


sendQ: Ptr; ( send buffer to remote end ) 
recvQ: Ptr; ( input buf from remote end ) 
attn: Ptr; — ( attention messages buffer ) 


outBuf: Handle; ( where outgoing data goes ) 
inBuf: Handle; ( where the input data goes 
attnBuf: Handle; ( where attention data goes 
remName: Handle; ( entity name of remote end 


rue м2 
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ccb : TRCCB; ( pointer to ccb ) 
attnPB: DSPParamBlock; ( attntion message pb ) 
dspPB: DSPParamBlock; ( connection pb 

user : Handle; ( place for user data ) 
End; 


( This is the listening connection ) 

ADSPPtr = ^ADSPBlock; 

ADSPBlock = Packed Record( ADSP protocol data) 
dspRefNum : Integer; ( driver refnum } 
ccbref : Integer; ( listener ccbRefNum) 
addr : AddrBlock; ( listener socket ) 
ends : CBPtr; (connections list } 
ccb : TRCCB; ( listener ccb 
pb : DSPParamBlock;{ pb for listener) 
chkPoint : Integer; ( set if in callback) 
oldSelf : Byte; (old self-send flag) 
pad : Byte; ( keep em even 

End; 


Str31 = StringI[31]; 
End. 


Listing 2. Constent and Type declarations for ADSP 
connections 


(YEZFTXX1X1XXXXXKXXKXXXX1XXXXXXXXXXXX) 
(*file: NBPXCMD.p x) 

(* *) 

(* Constant and tupe *) 

(* decalarations for nbp *) 

(* xcmds х) 

Сх --------%) 

(* @ Donald Koscheka *) 
(*6-October, 1988  *) 

(*A11 Rights Reserved *) 


(* х) 

(X — #) 

(* Date |  Description*) 
œ — n 

(х 06-Oct-88| file created *) 
(к — 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ у 


UNIT NBPXCMD; 
(XXxxxx*xxxxxxxxxxxxxxxxXxXxsxtttt) 


INTERFACE 
(QOOOOOOEOEOODEEEX EE EE EEEEOEE E) 


USES Memtypes, QuickDraw, OSIntf, ToolIntf, AppleTalk; 


CONST 

ASYNC = TRUE; 

SYNC = FALSE; 

NODE_NAME = -16096; (% name in chooser (STR )*) 
MAXNODES 100; (% maximum nodes for zone*) 


NBPLSIZE - 120; (* size local buf for NBP*) 
NN = 30; (% 8names in lookup table*) 
ENTITYSIZE = 110; (* size of entity 5) 
CLOSE. OK = 0; (* not “CLOSE” critical *) 
CLOSE_NOW = 2; (% close down when done *) 


- 


TYPE 
Str31 = String[31]; 


NBPBIkPtr = ^NBPBlock; 
NBPBlock = RECORD 

Registered: BOOLEAN; (* true = registered*) 

EntCount : INTEGER;(* 8 of entities visible  *) 
LookUpBuffer : Handle; (* lookup buffer х) 
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NTEntry : NamesTableEntry;(* entry in names table*) 
КЕРІ оса! : array[ 1. .NBPLSIZE] of Char;(* used by NBP*) 


.END; 


END. 


Listing 3. Constant and Type declarations for NBP 
access 


(Qoocopocooooooooooocooooooooeeexur) 
(* file: ADSPOpen.p 50 
(* *) 


(* Open the “.DSP? driver *) 
(* and establish memoru for *) 
(* the ADSPBlock.Creates the *) 
(*connection listener 5) 

(* x) 

(* Requires these Globals *) 
(* GLOBALADSPDATA х) 

(* mySocketListener *) 


(* х) 

Са DEFINE THE GLOBALS BEFORE *) 
(* USING THEM *) 

(ж +) 


(* By: Donald Koscheka  *) 

(* Date: 10-Oct-88 х) 
(Y22XXXXXXXXXXXXXXXXXXXXFXXXXXXX) 
(YXXXX1XXXXXXXXXXXXXXXXXXXXXXX 


Build Sequence 


pascal “(adsp)*ADSPOpen.p -o "(hato)"ADSPOpen.p.o 
link -m ENTRYPOINT -rt XFCN=1300 -sn Main=ADSPOpend 
” (hato) “ADSPOpen.p.od 
“(libraries)“Interface.o д 
-0 “(hat)“SwitchBoard 


ЖЖЖАЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖ) 


($R-) 
($S ADSPOpen) 
UNIT Koscheka; 


(YX25X2XX4135XX5X155XX55X5X55X5) 
INTERFACE 


(XXXXXX*X*XX***xxxx*xxxxx*txxxxxxx) 


Uses MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 
HyperXCmd, AppleTalk, ADSP, adspxcmd; 


Procedure EntryPoint( paramPtr : XCmdPtr 2; 


(*XXX*XXXXxXxxXx*X*xxxxxxxxxxxxx***xx) 


IMPLEMENTATION 


(XXXXXXXXXXX£XXXxXXXxXxxxxxx*x*xx) 


PROCEDURE ADSPOpen( paramPtr: XCmdPtr 2; FORWARD; 


Procedure EntryPointC paramPtr : XCmdPtr 2; 
Begin 

ADSPOpen( paramPtr 2; 

End; 


Procedure ADSPOpen( paramPtr : XCmdPtr ); 
VAR 

refnum : integer; 

tempH : Handle; 

edsp : ADSPPtr; 

error : OSErr; 

mppPB : MPPParamBlock; 

longStr : Str255; 


($I XCmdGlue. inc ) 
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BEGIN 
error :- noErr; 
adsp := NIL; (*** assume not in uet***) 


(*** Retrieve pointer to our globals ***) 
tempH := GetGlobal( ‘GLOBALADSPDATA’ ); 


(*** If it in, convert it to a pointer***) 
IF CtempH O NIL) AND CtempH^ € NIL) THEN 
BEGIN 
HLockC tempH ); 
ZeroToPas( tempH^, longStr ); 
adsp :- ADSPPtrC StrToLongC longStr 20; 
HUnlock€ tempH 2; 
END; 


IF adsp = NIL THEN 
BEGIN 
error := MPPOpen; 


IF error = noErr THEN 
BEGIN 
(*** Open the ADSP Driver ***) 
(*** ADSP driver must be in***} 
(*** your system folder **x) 
mppPB.newSelfFlag := 1; 
error := PSetSelfSend( @mppPB, SYNC ); 


error := OpenDriverC ‘.DSP’, refnum ); 
END; 


(*** set up connection listener ***) 
IF error = noErr THEN 
BEGIN 


adsp := ADSPPtr( NewPtr( sizeOf( ADSPBLOCK ) )); 


IF adsp <> NIL THEN 
WITH edsp^ DO 
BEGIN 
addr .aNode := 
addr.aNet := Ø; 
addr .aSocket := Ø; 


ends := NIL; 

dspRefNum :- refnum; 

oldSelf := mppPB.oldSelfF lag; 

ccbRef := Ø; 

chkPoint := CLOSE. OK; 

WITH pb DO 

BEGIN 

( OKAY to open a listening socket ) 
ioCRefNum := refnum; 


csCode := dspCLInit; 
ioCompletion := NIL; 
ccbPtr := @adsp*.ccb; 
localSocket:= 0; 


error := PBControlC 8adsp^.pb, SYNC ); 
IF error = noErr THEN 

BEGIN 

( Listener is now all ears) 

ccbRef :* ccbRefNum; 

addr .aSocket :* localSocket; 

csCode :* dspCLListen; 


filterAddress.aNet := Ø; 
filterAddress.aNode := 0; 
filterAddress.aSocket:- 0; 
error := PBControlC @adsp*.pb, ASYNC ); 
END; 

END; 
END; (*** with adsp ***) 


(*** If adsp opened ok, we have a socket***) 
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(*** so put away the data and the socket***) 
IF error = noErr THEN 
BEGIN 
SetGlobalC'GLOBALADSPDATA ^ , 
PasToZeroC NumToStr(LongInt(adsp)))); 


SetGlobalC 'mySocketListener ’, 


PasToZeroC NumToStr(LongInt(adsp*.addr)))); 


END 
ELSE 
DisposPtr( PtrCadsp) ); 


END 
END; 


IF error = noErr THEN 
paramPtr*.returnValue := PasToZero( '" ) 
ELSE 
peramPtr^.returnValue := 
PasToZeroCnumToStr(longintCerror ))); 
END; 


end. 


Listing 4. ADSPOpen() XFCN 


бі AERA жже) 
(*file: NBPOPen.p *) 

(ж ж) 

(* Create the control block and*) 

(ж initialize the data for *) 

(* the name binding protocol *) 

(* (nbp) stuff. *) 

(* *) 

С ---------%) 

(* @ Donald Koscheka *) 
(*6-October, 1988 *) 

(*A11 Rights Reserved х) 

(* *) 

С --------- x) 

(* Date | Description *) 

С ---------%) 

(ж 06-0сі-88 | file created 50 

С —, a , P — X) 

(Y22255 5XX55X5XXXXXXXXXXXXXXXXXXXXXXXX) 


(YXYXXXXXX1XXXXXXXXX1XXXXXXXXXXXXXKXKKXX 


MPW Build Sequence 


pascal “(nbp}*NBPOpen.p -o *(hato)^NBPOpen.p.o 

link -m ENTRYPOINT -rt XFCN-2001 -sn Ма in=NBPOpend 
” (hato) "МВРОреп.р.09 
“(libraries)” Interface.o à 


-0 “(hat)”“SwitchBoard 
ео а 


($R-) 
($S NBPOpen) 


UNIT Donald_Koscheka; 


(YXX2X24XXXXXXXXXXXXXXXXXXXXXXXX XX) 


INTERFACE 
(Y32125XX335355355X55X555XX5XXXXXKK) 


Uses MenTypes, QuickDraw, OSIntf, 
ToolIntf, PackIntf, HyperXCmd, 
AppleTalk, nbpxcmd; 


Procedure EntryPoint( paremPtr : XCmdPtr ); 


(EEXOXEEEEEXOEEEXGGEOOUEEEXOEEEEEX ) 


IMPLEMENTATION 
(жжке) 
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PROCEDURE NBPOpen( paramPtr: XCmdPtr 2; FORWARD; 


Procedure EntruPoint( paramPtr : XCmdPtr ); 
Begin 

NBPOpen( paramPtr ); 
End; 


Procedure NBPOpen( paramPtr : XCmdPtr ); 

(ЖЖЖЖЖЖЖЖХЖЖЖЖАЖЖЖЖАЖЖАЖЖЖАЖЖЖЖЖАЖЖЖАЖЖЖЖЖ 

x This routine initializes some common 
memory for use by the Name Binding 
Protocol (NBP) Driver and the XCMDs that 
will use it. 


x 

x 

x 

x 

* YOU MUST CALL THIS ROUTINE BEFORE 

* ANY OF THE OTHER XCMDs/XFCNs in the 
* AppleTalk suite. Failure to do so 
* will result in wildly unpredicatable 
* and possibly fatal performance by 

* hypercard. 

x 

* IMPORTANT: 

* THE HYPERCARD VARIABLE 

ж *GLOBALNBPDATA^ MUST BE 

* DECLARED IN YOUR SCRIPT 

* BEFORE CALLING NBPOPEN 

x 
x 
x 


Out: Error Result is returned to hypercard 
or empty if no error 
HKKKKKKKKKEK KAKA AKA KAKA KEKE ) 
VAR 
i : INTEGER; (*** just a loop counter ***) 
tempH: Handle; (xs Used to get global ***) 
nbp : NB8PBIkPtr; (*** MUST NOT MOVE ххх) 
error: OSerr; (%%% allocate as pointer ***) 
longStr: Str255; (*** for ZeroToPas call ***) 


($I XCMDGlue.Inc ) 
BEGIN 
error := noErr; 
nbp := NIL; (*** assume no data yet ***) 


(*** Retrieve the pointer that’s stored *%%) 
tempH := GetGlobalC ‘GLOBALNBPDATA’ ); 


(*** If it’s defined, convert it to a pointer***) 
IF CtempH © NIL) AND CtempH* € NIL) THEN 
BEGIN 
HLockC tempH ); 
ZeroToPasC tempH^, longStr 2; 
nbp := NBPBIkPtrC StrToLong( longstr 2); 
HUnlockC tempH 2; 
END; 


IF nbp = NIL THEN 
BEGIN 


(*** Allocate nbp, initialize its fields***) 
nbp := NBPBIkPtr(NewPtr( sizeof( NBPBlock ))); 


IF nbp «> NIL THEN 
WITH nbp* DO 
BEGIN 
WITH NTEntry DO 
BEGIN 
nteAddress.aSocket:= 0; 
nteAddress.aNode := 0; 
nteAddress.aNet:= 0; 


For i := 1 TO 100 DO 
nteData[i]:- chr(0); 
END; 
(*** Clear at the lookup stuff ***) 
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Nu 


Pa 
EN 
EN 
Li 


(* 
(* 
(* 
(* 
(* 
(* 
(ж 
(ж 
(ж 
(* 
(* 
(* 
(* 
(* 
(x 
(* 
(* 
(* 
(* 


pa 
11 


xx 


(*** (signifies no lookup yet) ***) 
LookUpBuffer := nil; 

EntCount 0; 

Registered FALSE; 


SetGlobal( ‘GLOBALNBPDATA’ ,РавТо7его( 


mToStrCLongInt(nbp)))); 
END 
ELSE 
error := -1; (*** some sort of error occured ***) 
END; 


(*** Note that no error is reported ***) 
(*** as ‘empty’, rather than @. This ***) 
(*** is in keeping with HyperCard  ***) 
IF error = noErr THEN 
peramPtr^.returnValue :- PasToZeroC ”” ) 
ELSE 
paramPtr^.returnValue := 
sToZero(numToStrClongintCerror 22); 


D; 
D. 
sting 5. NBPOpen() XFCN 


X X Xxoooeoeooceoooooooeoebpeboooevee)) 


file: ADSPClose.p 50 
х) 
Close down {ће connection *) 
listener and all open *) 
connections. x) 
Set the globals to emptu *) 
х) 
Requires these Globals *) 
GLOBALADSPDATA х) 
mySocketListener х) 
х) 
DEFINE THE GLOBALS BEFORE *) 
USING THEM ж) 
-----------Х) 
By: Donald Koscheka *) 
Date: 10-Oct-88 х) 
XXXcOOOOOOOOOOOODOEOOOEOEREXEXE E) 
HAKKAR EKER KE KK KKK 


Build Sequence 


scal "(adsp)^ADSPClose.p -o "(hato)"ADSPClose.p.o 
nk -m ENTRYPOINT -rt XFCN=1301 -sn Main=ADSPClosed 
* (hato) “ADSPC lose .p.od 

“(libraries}*Interface.o д 

-о "(hat)"SwitchBoard 


XXXXXXXXXXXXXXXXFXXXXXXKXXXKXXX) 


($R-) 


($ 
UN 


(* 
(* 
Us 


Pr 
(* 


(* 


S ADSPClose} 
IT Koscheka; 


XXXXXXXX1X1F1X1X1XXXXXXKX1KKIXXXKKXKKE) 


INTERFACE 


$$3999999222 22922222 22 22222 22 У 


es МепТуре5, QuickDraw, OSIntf, ToolIntf, PackIntf, 
HyperXCmd, AppleTalk, ADSP, adspxcmd; 


ocedure EntryPoint( paramPtr : XCmdPtr ); 
KKKKKKKKKKAKAKAAAKAK AKA KAEK 22222222 


IMPLEMENTATION 


$$999999229292 2322 2222222222222 


PROCEDURE ADSPClose(C paramPtr: XCmdPtr 2; FORWARD; 
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Procedure EntryPoint( paramPtr : XCmdPtr ); 
Begin 
ADSPCloseC paramPtr ); 
End; 


Procedure ADSPClose( paramPtr : XCmdPtr ); 
VAR 

tempH : Handle; 

adsp  : ADSPPtr; 

error,err : OSErr; 

tpb : DSPParamBlock; 

cb, nb : CBPtr; 

mppPB : mppParamBlock; 

longStr : Str255; 


($1 XCmdGlue. inc ) 


BEGIN 
error := noErr; 
adsp := NIL; 


(*** Retrieve the pointer ***) 
tempH := GetGlobal( ‘GLOBALADSPDATA’ ); 


IF CtempH © NIL) AND CtempH^ € NIL) THEN 
BEGIN 
HLock( tempH ); 
ZeroToPas( tempH*, longStr ); 
adsp := ADSPPtrC StrToLong( longStr )); 
HUnlock( tempH ); 
END; 


(хаж Only kill if allocated **x) 

IF adsp € NIL THEN 

WITH adsp* DO 

BEGIN 
(* 1 - Tear down connection listener*) 
IF pb. ioResult > Ø THEN 


WITH tpb DO 

BEGIN 
ioCRefNum := dspRefNum; 
csCode := dspCLRemove; 
ccbRefnum := adsp^.ccbref; 
abort LS 


err :- PBControlC 8tpb, SYNC 5; 
IF err © noErr THEN error := err; 
END; 


(* 2 - Restore old self send *) 
mppPB.newSelfFlag := adsp^.oldSelf; 
err := PSetSelfSend( @mppPB, SYNC ); 


(* PSetSelfSend not implemented on*) 
(* Mac* (???), so ignore result*) 

(* “driver can't respond to this *) 
(* control call’. x) 


(* 3 - Deallocate all ADSP memoru*) 
DisposPtr( Ptr( adsp ) ); 


(* 4 * Clear out the containers*) 


SetGlobal( ‘GLOBALADSPDATA’, PasToZero(’’)); 


(* 5 - leave socket address valid*) 
(*for now x) 
END; (*** WITH adsp* ***) 


IF error = noErr THEN 


paramPtr .returnValue:=PasToZero(‘’) 
ELSE 
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paramPtr-.returnValue:=PasToZero(numToStr(longint(error))); 
END; 


END. 
Listing 6. ADSPCloseC) XFCN 


Coooocceooeooooooooooooooocoboeoec ) 
(*file: nbpClose.p *) 

(* x) 

(* Create control block and *) 
(* initialize the data for *) 

(* the name binding protocol *) 


(* (nbp) stuff. *) 
(* *) 
С -------- а) 


Сх € Donald Koscheka х) 
(*6-October, 1988 x) 

(*A1] Rights Reserved *) 

(* х) 
(kkkkkkkkkkkkkkkkkkkkkkkkkkkkxkx) 
(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


MPW Build Sequence 


pascal "(nbp)^nbpClose.p -o *(hato)“nbpClose.p.o 
link -m ENTRYPOINT -rt XFCN-2002 -sn Main=nbpClosed 
* (hato) "nbpClose.p.o8 
* (Vibraries)"Interface.o д 


-o *(hat)"SwitchBoard 
X coXxoXceoocooorooooroeoooooooooooceo) 


($8-) 
($S nbpClose) 
UNIT Donald.Koscheka; 


Qoooooccoecoooeoooooooooooooeeee) 
INTERFACE 


(ЖЖЖЖЖЖЖЖЖЖЖЖХАЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


Uses MemTypes, QuickDraw, OSIntf, 
ToolIntf, PackIntf, НурегХСта, 
AppleTalk, nbpxcmd; 


Procedure EntryPoint( paramPtr : XCmdPtr ); 


(YXXXXXXXXXXKXXX1XXX1XXXXXKXKXKXKE) 


IMPLEMENTATION 
CQooeeooccoocoooeooooooooopoeeeeeec) 


PROCEDURE nbpClose( paramPtr: XCmdPtr 2; FORWARD; 


Procedure EntryPoint( paramPtr : XCmdPtr 2; 
Ведіп 

nbpClose( paramPtr ); 
End; 


Procedure nbpClose(paramPtr : XCmdPtr); 
(ЖЖЖЖЖАЖЖЖХХЖАЖЖЖЖЖЖЖЖХАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


* This routine shuts down access to 


the NBP driver. It also unregisters 
the entity if that hasn’t already been 
done. 

IMPORTANT : 


THE HYPERCARD VARIABLE 
“GLOBALNBPDATA” MUST BE 
DECLARED IN YOUR SCRIPT 
BEFORE CALLING nbpClose 


% к »* и ж ии * x * м М 


Does not report an error 
XXOCCOOOODOODOEOICEIOOROROIOOIOOIGEOOIOOROIOEO OEC ) 


VAR 
error : OSErr; 
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longStr : Str255; 

tempH : Handle; 

nbp : NBPB1kPtr; (*** MUST NOT MOVE ***) 
pb : MPPParamBlock; 


($I XCMDGlue.Inc ) 


BECIN 
error := noErr; 
nbp := NIL; (*** assume no data yet ***) 


(жжж Retrieve the pointer that’s stored ***) 
tempH := GetGlobalC 'GLOBALNBPDATA^ 2; 


(жжж If it’s there, convert to pointer ***) 
IF CtempH <> NIL) AND CtempH^ € NIL) THEN 
BEGIN 
HLock( tempH ); 
ZeroToPasC tempH^, longStr 2; 
nbp := NBPBIkPtrC StrToLong( longStr 22; 
HUnlockC tempH 2; 
END; 


(жжж If the data is still allocated, we ***) 
(жжж shut down NBP, otherwise, just quit***) 
IF nbp О NIL THEN 
WITH nbp^ DO 
BEGIN 
(*** Unregister if still registered***) 
IF NTEntry.nteData( 1) © chr(0) THEN 
BEGIN 


pb.entityPtr := @NTEntry.nteDatal 1); 
error := PRemoveName( @pb, SYNC ); 


END; 


(*** Remove the lookup buffer ***) 
IF LookUpBuffer ‹› NIL THEN 


BEGIN 


HUnlock( LookUpBuffer ); 
DisposHandleC LookUpBuffer ); 


END; 


(*** Dump the NBP Master Block **X) 
DisposPtrC Ptr(nbp) 2; 
SetGlobalC ‘GLOBALNBPDATA’, РавТо7его( '^ 2); 


END; 


IF error = noErr THEN 


paramPtr^.returnValue :- PasToZero( ”” 2 


ELSE 


peremPtr^.returnValue := 
PasToZero(numToStr(ClongintCerror 22); 


END; 
END. 


Listing 7. NBPCloseC) XFCN 
Next month: Accessing the Name Binding Protocol in 


HyperCard. 
end HyperChat 


Sel 


EPS 
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HyperChat!M 
A Real Window XCMD 


HuperCard 


Joe Zuffoletto 
Cupertino, CA 
Volume 5, Number 2 


Window XCMD 
Part 1: Windows, XCMD's, and MultiFinder 

Joe has been at Apple a little over a year,where he works in 
the Software Quality Assurance department. His group develops 
automated software test tools. Before coming to Apple, He 
earned a BS in EE & CS from Princeton University. He has been 
programming the Macforabout8months and spends alot of time 
experimenting with HyperCard. This article contains important 
windowing technology for dealing with gray regions, contir- 
buted by Scott Boyd and Greg Marriott. 

Of Cards and Windows 

For some reason, XCMD's that put up windows intrigue me. 
I think it’s because windows imply event loops, and running an 
event loop in an XCMD is an interesting idea because it allows 
you to temporarily “steal the show” from HyperCard. Also, once 
you throw a window on the screen there’s a lot of neat stuff you 
can put inside it, like graphics too large for HyperCard’s card 
window, files generated by other applications, color pictures, and 
human interfaces for sophisticated tasks. 

In this article I will present an XCMD that displays a 
document window with scroll bars. This XCMD is full-featured 
and very robust — essentially a mini-Macintosh application 
running on top of HyperCard. Itis MultiFinder aware, shows how 
to scroll bitmapped graphics documents, and also demonstrates 
how to support multiple screens on the Mac II. Finally, it 
demonstrates how to cope with some human interface issues 
when it comes to displaying windows on top of HyperCard. 
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Figure 1a: Before... 
My discussion assumes you are somewhat familiar with the 
issues behind writing XCMD's and XFCN's for HyperCard. In 
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Figure 1b: ...After 


particular, I assume you have a nodding acquaintance with the 
glue routines that perform special functions and facilitate com- 
munication between your XCMD and HyperCard. Plenty of 
introductory articles on the subject have appeared in MacTutor 
over the past few months, and Gary Bond has written an excellent 
book, XCMD's for HyperCard (MIS Press, 1988), which gives 
you a head start in writing XCMD’s (Like Gary, I refer to 
XCMD’s and XFCN's simply as XCMD's). 

However, even if you are not writing XCMD's you might 
learn a lot of useful stuff by reading this article. My XCMD uses 
an event loop much like one you would find in a normal 
application, and I show you how to cope effectively with event 
handling and cursor tracking under MultiFinder. Also, if you'd 
like to see a rare example of scrolling code, that will be coming 
next month. In short, there's something here for just about 
everyone. 

One article will not hold all this material, so I’m splitting it 
into two parts. This month I will show you how to put the window 
up and deal with MultiFinder, multiple screens, and human 
interface issues. The window will have scroll bars but they won’t 
work. Next month I'll breathe life into the scroll bars by demon- 
strating techniques for scrolling bitmapped graphics documents. 
As a newcomer to Mac programming I feel there is a critical 
shortage of example scrolling code, so I'd like to add some to the 
pool. 

First Stop: The Drawing Board 

I would like to start by describing the design of this fairly 
extensive XCMD, which I call Window. 

The goal is to create a “full-featured” window — one that is 
draggable, growable, zoomable, and contains scroll bars. Some 
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other aspects of the design: 

e Window is “semi-modal.” This means we cannot use 
HyperCard while the window is up, but we can switch to other 
applications under MultiFinder. Boo! Hiss! Yecch! Unfortu- 
nately, this “feature” is imposed on us by HyperCard, which, like 
all Macintosh applications, doesn’t like to share its event loop 
with strangers. 

• Window is “MultiFinder aware;” i.e., the main event loop 
calls WaitNextEvent and handles suspend/resume events. We 
don’t need a SIZE resource because we’re running under the 
auspices of HyperCard and are using whatever space is available 
in HyperCard’s application heap. Window doesn’t use the clip- 
board, so it doesn't need to convert its own private scrap when the 
user clicks on another open application. This feature could be 
added, however. 

If you'd like more information about programming under 
MultiFinder, see the “Programmer’s Guide to MultiFinder," an 
Apple publication available from APDA. 


° Window supports multiple screens on the Mac II. This 
means the window can be dragged to any screen, grown 
or zoomed to the size of the largest screen, or grown to 
span adjacent screens. If the user clicks on the zoom box, 
the window zooms to whatever screen the zoom box is on 
at the time, instead of the default behavior of zooming to 
the main screen. 

Window accounts for human interface anomalies intro- 
duced by HyperCard. This means it deals sensibly with 
HyperCard's windoids and with the current state of the 
menubar, which may or may not be visible when Window 
is invoked. As we'll see, inattention to the state of the 
menubar can get you into trouble under MultiFinder! 

The HyperTalk call is: 

Window title,top,left,bottom right 

where title is a string (enclosed in double quotes), and 
the other parameters are integers specifying the window's 
screen location in global coordinates; i.e., (0,0) is the top 
left corner of the screen (or of the main device on a Mac 
ID, with coordinates increasing as you move down and 
right. 

Window won’ tallow you to draw a window whose title 
bar is off the screen or under the menubar. 

Command-spacebar toggles the menubar off and on, 
just like in HyperCard. If the menubar is visible and the 
user clicks the mouse outside the window, the menubar 
flashes unless the click causes MultiFinder to switch to 
another open application. 

Clicking on the window's close box ends the XCMD. 
Command-W, which closes windows in the Finder and 
many other applications, is also supported for this pur- 


pose. 


For now, the window we put up will be empty, but will 
demonstrate all of the features described above. Next month I'll 
add contents to the window when I talk about scrolling. 
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Plan of Attack 

Now that we know the main features of the XCMD, it's time 
to think about what steps to take to implement them. 

Window, of course, will have an event loop, much like a 
normal Macintosh application. Because of its semi-modal na- 
ture, however, Window will not respond to mouse clicks inside 
HyperCard's card window or menubar. Instead, it will just flash 
the menubar. 

Incidentally, we could put up our own menubar and turn 
Window into a true mini-application, and then restore the 
menubar to HyperCard's on exit. As soon as someone thinks of 
a useful mini-application that runs as an XCMD they will do this, 
but for now let's keep things simple and ignore the menubar. 

By the way, because we're ignoring the menubar, what will 
happen under MultiFinder when the user clicks on the applica- 
tion icon in the upper righthand corner? Will we switch applica- 
tions? Yes! This is the other side of Window's semi-modal 
nature. The only thing that prevents MultiFinder from switching 
in this situation is if the frontmost window is of the dBoxProc 
type, which MultiFinder associates with modal dialog boxes. Our 
window is of type zoomDocProc, so MultiFinder will switch. 
MultiFinder will also switch if we click on a visible window 
belonging to a different application. 

I want to avoid adding extra resources (besides the XCMD 
itself) for the user to copy into his or her stack, so I'll use 
NewWindow to build my window on the fly instead of pulling it 
out of a resource with GetNewWindow. This is no big deal 
because the window is just a standard document window with a 
zoom box. 

As with writing desk accessories, we can have no global 
variables. This should be no problem. 

Early Frustrations 

If you have ever tried to put a window on top of HyperCard 
with an XCMD, you probably experienced all kinds of interest- 
ing and unexpected problems. You will therefore recognize some 
of the obstacles I encountered in early development, which I will 
now describe to you — solutions included. 

The first problem is a complete show-stopper with the 
following symptoms: The XCMD successfully puts up some 
kind of window — a dialog box, document window, or whatever 
— but then bombs consistently on exit. Inspecting the code 
reveals no obvious problems. What on earth could possibly be 
wrong? The answer is contained in the following Fundamental 
Law: Thou shalt save the current grafPort upon entering thy 
XCMD and restore it upon leaving. 

When an XCMD starts, the current grafPort is always 
HyperCard's card window, and HyperCard expects things to be 
no different when the XCMD ends. If you set the port to 
something different, say to a window you put up or to a printing 
grafPort, and then don't set it back, HyperCard gets very con- 
fused and dances La Bomba. 

Let's now assume the grafPort problem is solved and we 
have a window up that can be dragged, grown, and zoomed. The 
next problem pertains to update events; namely, the HyperCard 
window and the little windoids don't seem to be getting any. 
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Instead, when we drag our window on top of them and move it 
away, big white blotches remain. But under MultiFinder, when 
we drag our window over other applications and move it away, 
they update normally. What's going on here? 

The answer to this question is fairly interesting, and the 
described behavior under MultiFinder adds additional insight. 
First of all, it should be clear why the other applications update 
normally: It's because MultiFinder sends them update events 
whenever our window’s movements corrupt their displays. Well 
then, shouldn’t MultiFinder be sending HyperCard update 
events for the same reason? Yes, it should, and indeed it is, but 
update events for HyperCard are being intercepted by our 
XCMD’s event loop! 

At this point we have two choices. We can either throw up 
our hands and live with the white blotches, or we can figure out 
a way to pass update events to HyperCard. Following the second 
path is best, of course, but before you dive into your MultiFinder 
documentation to figure out how to fake an app4 event, think for 
a minute about the HyperTalk callback routines. These are 
routines like ZeroToPas, GetFieldByName, SendHCMessage, 
StrToNum — hey, wait a minute! SendHCMessage! That sounds 
promising... As you may know, SendHCMessage delivers 
messages from XCMD’s to HyperCard (and its cousin, Send- 
CardMessage, delivers messages from XCMD’s to the current 
card). Maybe we can do something like this when we get an 


update event: 
VAR 
myWindow: WindowPtr; 
HCPort: GrafPtr; 
BEGIN 


GetPortCHCPort); 
CASE myEvent.what OF 


updateEvt: 
BEGIN 
IF WindowPtr(myEvent.message) = 
myWindow) THEN 
BEGIN 
SetPort(muWindow); 
BeginUpdate(muWindow); 
DoUpdate(muWindow); 
EndUpdate(muWindow); 
END 


ELSE IF 

WindowPtr(muEvent.message) 

= WindowPtr(HCPort)) THEN 
SendHCMessage( ‘updateEvt’); 


END; 

This is the right idea, but SendHCMessage takes only legal 
HyperTalk commands as input parameters! Which HyperTalk 
command(s) will send an update event to the card window? It 
turns out that going to any card (including the current card) will 
do the trick. Since we don’t want to switch cards on the user in 
the middle of our XCMD, let's replace the bogus SendHCMes- 
sage command above with 

SendHCMessage('go to this card’); 

and, like magic, both our window and the card window will 
get update events when they need them. But what about the 
windoids? They still suffer from white-blotchitis. 


@ The Best of MacTutor, Vol. 5 


Egads! Human Interface Issues! 

This is where we can be good boys and girls and think about 
Human Interface Issues. Every Mac programmer should do this 
at least once in his or her lifetime, and here's a wonderful 
opportunity to get it over with. We know our window is semi- 
modal, which implies it is on top of every other window in our 
layer, including the windoids. We also know that the user can’t 
use any of the windoids while our XCMD is running because we 
don’t know how to process events in them. Despite all this, the 
windoids remain hilited and appear to be as active and available 
as ever — a potentially confusing situation for the user. So why 
don’t we hide them? 

I happen to think this is a Very Good Idea, and I would like 
to propose that all HyperCard authors, be they XCMD writers or 
HyperTalk scripters, observe the following guidelines when 
creating their products: 

° Always hide windoids upon entering event-driven 
XCMD's or XFCN's. 

* Please don't hide windoids from within HyperTalk scripts 
unless absolutely necessary. Leave the menubar alone, 
too. 

* Whenever you hide windoids, get and save their current 
state (i.e., which ones are visible, where they are located 
on the screen, and which tools/patterns are selected) and 
return them to that state when you are finished. The same 
goes for the menubar. 


If I make only one contribution to the Macintosh program- 
ming community before I die I hope it is the italicized guideline 
above. I spend a fair amount of time customizing my HyperCard 
environment, and I have all the windoids displayed right where 
I want them. I just can't stand it when someone's script comes 
along, blows them all away for no apparent reason, and then 
leaves it to me to put them back. Verrry rude. I also can't stand 
it when people take the menubar away from me and never restore 
it, especially on a Mac II. 

For the purpose of writing event-driven XCMD’s, we can 


satisfy the first and third guidelines with the following code: 
CONST 


mBarHeight = $BAA; (global) 
VAR 
toolVis,menuVis: BOOLEAN; 
toolH: Handle; 
menuBarHeight: INTEGER; 
menuBarHeightPtr: “INTEGER; 
BEGIN 
(Get and save current state of 
windoid) 
toolH := EvalExprC'visible of tool 


window’); 
ZeroToPasCtoolH*, toolStr); 
DisposHandleCtoolH); 
toolVis := StrToBoolCtoolStr); 
IF toolVis THEN 
sendHCMessage( ‘hide tool 
window’); 


(Get and save current state of 
menuBar } 
menuBarHeightPtr :- 
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Pointer(mBarHeight); 
menuBarHeight := menuBarHeightPtr° ; 
IF menuBarHeight > 0 THEN 

menuVis := TRUE 
ELSE 

menuVis := FALSE; 


("Meat^ of XCMD goes here") 


(Restore windoid when finished) 
IF toolVis THEN 
SendHCMessage( ‘show {001 
window’); 
(Restore menubar if you changed it) 


Of course, we would repeat the tool windoid code for the 
pattern and message windoids. You don’t need to worry about the 
locations of the windoids because HyperCard “remembers” their 
positions between hide and show commands. 

HyperCard has one other windoid called FatBits that ap- 
pears whenever you go into fatbits mode, but there are no 
HyperTalk commands to hide it or show it! Fortunately, Bill 
Atkinson names all his windoids, and the HyperCard people tell 
me the names won't change, so all we have to do is walk the 
window list until we find the window called “FatBits,” then hide 
it if appropriate. I accomplish this in the HideFatBits procedure, 
which is nested in HideWindoids. Once HideFatBits finds the 
FatBits window, it saves the WindowPtr to it so we can show it 
again (if necessary) in the RestoreWindoids routine. 


Aack! More Human Interface Issues!! 

OK, as long as we're hiding the windoids, why not hide the 
card window? And since we're ignoring the menubar, we might 
as well get rid of it too, right? 

I don't have strong opinions about either of these ideas. 
Concerning the card window, I prefer to leave it up for four 
reasons. First, the current card may contain information we want 
to see while we are looking at the contents of the window. 
Second, leaving the card window showing gives us a visual 
reminder of who owns the window when we are running under 
MultiFinder, because clicking on either window will bring 
HyperCard's layer to the front (with our window on top, of 
course). Third, it gets a little annoying to watch the card window 
disappear and reappear every time we invoke Window. And 
fourth, since larger human interface concerns are not at stake here 
(as they are with the windoids), I’m content to let the user decide 
in his or her HyperTalk script whether or not the card window will 
be left showing. 

I solve the menubar problem by allowing the user to toggle 
it with command-space, just like in HyperCard. 


Dashing through the Code... 

Once I got past the initial obstacles and human interface 
issues, coding the XCMD was fairly straightforward. In this 
section I'll zip through the program listing and give you some 
idea of what's going on. Remember that I'm going to cover the 
scrolling of bitmaps next month, so all the scrolling and bitmap 
routines are stubbed out. 

Take a look at the Main Program. The first thing we do (after 
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checking the HyperCard version and saving thy grafPort) is make 
sure the number of input parameters sent to us is correct by calling 
CheckParamCount. CheckParamCount tells us nothing about the 
parameter types; if they're mixed up or wrong we could be in 
trouble. 

Assuming the input parameters are cool, we use the standard 
battery of ZeroToPas and StrToNum calls to convert them to 
useable form for our program. Then we hide the windoids and 
draw the window with scroll bars. 

Next we enter the main event loop, where we call WaitNex- 
tEvent (if available) and pre-process suspend/resume events if 
MultiFinder feeds them to us. I say “pre-process” because all we 
do here is set a flag telling us if we are running in the background 
or not. This information is used later when activate and update 
events are handled. | 


A Short Digression: 
Cursor Tracking with WaitNextEvent 
While we're talking about WaitNextEvent, let me say a few 
words about cursor tracking. Imagine a routine called AdjustCur- 
sor which does the following: 

1. Get the mouse location in global coordinates; 

2. Get the location and size of my window; 

3. If the mouse lies within my window's content region (minus 
the scroll bars), set the cursor to HyperCard’s browse tool, 
and setaregion called cursorRgn to region A (see Figure 2a); 

4. If the mouse lies outside region A, set the cursor to arrow, 
and set cursorRgn to region B (see Figure 2b). 


Ld 


é File Edit Go Tools Objects 


Inside:HyperCerd:Home 


Figure 2a 


In the old days (before WaitNextEvent), Macintosh pro- 
grammers would call a routine similar to AdjustCursor on every 
pass through the event loop because that was the easiest way to 
make sure the correct cursor was showing over various parts of 
a program's human interface. This technique, although reliable, 
is inefficient because lots of time is spent crunching through Ad- 
justCursor, even when the cursor is not moving. 

WaitNextEvent has an interesting feature that makes cursor 


@ The Best of MacTutor, Vol. 5 


tracking more efficient. If I call the hypothetical AdjustCursor 
routine and then pass a handle to cursorRgn as the last input 
parameter to WaitNextEvent, I will get a mouse-moved event 
from MultiFinder when the cursor leaves cursorRgn, and then I 
can call AdjustCursor again to update the cursor and redefine 
cursorRgn for next time. This saves me from needlessly updating 
the cursor on every pass through the event loop. 

This is very efficient, but using WaitNextEvent’s cursor 
tracking feature solves only part of the cursor tracking problem. 
Let me illustrate with an example. Assume I’m using the Wait- 
NextEvent feature, and let’s say my window is small and I’m 
going to zoom it to fill the screen. When I move to the zoom box 
from region A ГЇЇ get а mouse-moved event. Then ГІ call 
AdjustCursor to switch cursorRgn to region B and the cursor to 
arrow. So far, so good. 

Now if I zoom the window and don't move the cursor, the 
cursor will be sitting somewhere over my window's contents, 
where it should become the browse tool cursor. But it's still the 
arrow! Why? Because the old region B is still in effect (instead 
of a new region A), and a new region A won't be created until I 
cross into the old region A again! To solve this problem, I can call 
AdjustCursor immediately after zooming the window to account 
for the window's new size. But I'll experience the same problem 
after dragging and growing the window, so now I have to call 
AdjustCursor in these cases as well. Of course, I could just call 
AdjustCursor when I handle update events, but I still need to call 
it immediately after dragging the window because dragging 
doesn't always generate an update event in my layer. I think you 
can see my point — WaitNextEvent's cursor tracking feature is 
helpful because it saves you from calling AdjustCursor on every 
pass through the event loop, but there are a few special cases, 
mostly related to window movement and sizing, that you must 
handle yourself. Also, if you are calling GetNextEvent instead of 
WaitNextEvent, you must still use the old cursor tracking tech- 
nique (or a more efficient technique of your own invention). 

You might have noticed while using HyperCard that the 
cursor is kind of flaky. In particular, it is sometimes the arrow 
when it should be the browse tool, but if you move it outside of 
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the card window and then back again, the browse toolreappears! 
You can probably guess my theory as to why this happens.... 


The Main Event 
OK, we've pre-processed our MultiFinder events and ad- 
Justed our cursor. Now we can handle events in our window. Not 
too many surprises here — I'll zip through each event and 
summarize what's happening. 


MOUSE DOWN: 

Flash the menubar (when it is visible) if the mouse click is 
outside our window; otherwise: 

inDrag: 
° Drag the window. If you haven't read the Window 

Manager chapter of Inside Macintosh, Volume V, 

now’s a great time to do it. Notice I obtain the dra- 

gRect (the rectangle within which we can drag the 

window) by calling GetGrayRgn, which replaces old- 

Style references to the QuickDraw global 

screenBits.bounds and automatically takes multiple 

screens into account for us. 

° Update the card window (must do it explicitly 
because there is no update event in our layer) 

° Adjust the cursor region. 

inGrow: 

° Grow the window. The GrowWindow routine 

has been modified for multiple screen systems; 

again, see the Window Manager chapter of Inside 

Macintosh, volume V for details. 

° Move the scroll bars 

inZoomln,inZoomOut: 

* Zoom the window according to the rules 

implemented n the Zoomlt procedure. 

inContent: 

° Deal with scroll bars, if appropriate; otherwise 
ignore. 

inGoAway: 

° Exit event loop and XCMD! 

ACTIVATE EVENT: 

If inBackground is true, then we've just been sent behind 
another application under MultiFinder. We deactivate our scroll 
bars and show the menubar if it was hidden. MultiFinder will not 
take care of the menubar for us, and it’s terribly unkind to send 
the user off to another application without a menubar! 

Similarly, when we return, inBackground will be false. We 
reactivate our scroll bars and return the menubar to whatever 
State it was in when we left. 

UPDATE EVENT: 

If inBackground is true, then we have been fed an update 
event by MultiFinder because the user’s mousing around in 
another application has corrupted our window, HyperCard’s 
card window, or both. 

If our window is corrupted, we redraw our deactivated scroll 
bars and the other stuff in our window. 

If HyperCard’s window is corrupted, we update Hyper- 
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Card’s window without updating ours. We also call BeginUpdate 
and EndUpdate to empty the HyperCard window’ update region 
because SendHCMessage alone doesn’t do this, and we'll get 
into an infinite loop of update events if we don’t do it ourselves. 

If inBackground is false, then we have been fed an update 
event because our window has either been grown or zoomed. 

If our window is corrupted, we redraw our activated scroll 
bars and the other stuff in the window. Then we adjust the cursor. 

If HyperCard’s window is corrupted, we update it as de- 
scribed above. 


KEYDOWN: 

The only other event that concerns us is keyDown. If we get 
command-space, we toggle the menubar off and on, just like in 
HyperCard. If we get command-W, we close the window and 
leave the XCMD. 


Sneak Preview 

That does it for putting up the window, building an event 
loop, and dealing with MultiFinder. Next month I'll describe the 
routines and data structures for scrolling and offscreen bitmaps, 
which are stubbed out in this month's code listing. I'll show you 
how to set up an offscreen bitmap, then I'll demonstrate a 
technique called blitting that produces flicker-free, high-speed 
scrolling. 

Thanks, Everybody! 

At this point I would like to mention a few people whose 
ideas and assistance were of great help to me in this glorious 
project. At the top of the list is “Mr. Toolbox” himself, Greg 
Marriott, who responded to most of my questions with an 
understanding nod and a correct answer. Greg also supplied the 
code for zooming the window on multiple screens. 

Not far behind is “Mr. Window Manager,” Scott T Boyd, 
who taught me how to live without the QuickDraw globals. 

[MacTutor readers will be very familar with both Scott Boyd 
and Greg Marriott as contributors and friends of MacTutor 
particularly during their "MacHax days". -Ed] 

Thanks to Steve Maller for teaching me how to update 
HyperCard’s window, and to Ginger Jernigan, who took time to 
review the manuscript. 

Thanks to Gary Bond for his excellent book on writing 
XCMD's, and for the time he took to review the manuscript. 

And, gosh, I almost forgot: Thanks, Bill! 


(* 


@ 1988, Apple Computer, Inc. 
All rights reserved. Publication rights granted to Maclutor. 


Windowl.p: А HuperCard XCMD in MPW Pascal 2.0.2 
bu Joe Zuffoletto 
Version 1.0, 29 June 1988 

Form: Window title,top, left,bottom,right 

Example: window "My Window^,50, 100,300, 400 

Notes: Window puts up a standard document window with 
scroll bars. The window can be dragged, resized, 
zoomed, and closed. 
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Command-W is supported for closing the window. 
Command-spacebar toggles the menubar on and off, 
as in HyperCard. If you try to draw the window’s 
title bar off the screen or under the menubar, 
Window will abort with an error message. Error 
messages can be examined by looking at 
HyperCard’s global variable “the result” after 
calling Window. 


Window is MultiFinder friendly and works with 
HyperCard 1.2 or later. It supports multiple 
displays on the Mac II as well. 


You must supply your own code for displaying 
whatever you want to display in the window. 


To compile and link this file using MPW Pascal 2.0.2, select 
the following lines and press ENTER: 


Pascal Windowl.p 

link -o “Hard Disk” :HyperCard: “HyperCard Stacks” :Ноте à 
-rt XCM0-2000 -sn Main=Window 9 
Windowl.p.o (MPW)Libraries:Interface.o д 
(MPW)PLibraries:PesLib.o д 
-m ENTRYPOINT 


Use other link files as necessary. 


The above link directives install the XCMD resource into the 
Home stack. You can substitute the name of any stack you want; 
be sure to provide the correct pathname. Also, make sure the 
target stack already hes a resource fork or it won't work. You 
can create an empty resource fork in a stack 

with ResEdit. 


х) 

($R-) 

($S Window) 
UNIT DummuUnit; 
INTERFACE 


USES 


Memlupes,QuickDraw,OSIntf,ToolIntf,PasLibIntf,HuperXCmd; 
PROCEDURE EntruPoint(paramPtr:XCmdPtr); 
IMPLEMENTATION 
ТҮРЕ Str31 = String[31]; 


OffScrHandle = “Of fScrRecPtr; 
(Attach to refCon of a window) 
Of fScrRecPtr = “Of fScrRecord; 
OffScrRecord = RECORD 
(Next month!) 
END; 


ScrollHandle = “ScrollPtr; 
(Attach to refCon of a control) 
ScrollPtr = ^ScrollRecord; 
ScrollRecord = RECORD 
(Next month!) 
END; 


PROCEDURE Window(paramPtr :XCmdP tr > FORWARD; 
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PROCEDURE EntruPoint(paramPtr:XCmdPtr); 
BEGIN 

Window(paramPtr); 
END; 


FUNCTION MinCint1, int2: INTEGER): INTEGER; 
BEGIN 

(Next month!) 
END; (Min) 


PROCEDURE InitBlitCtheWindow:WindowPtr); 
BEGIN 

(Next month!) 
END; (InitBlit) 


PROCEDURE InvalContentsCtheWindow:WindowPtr; 
{ће019512е:Кесі); 
BEGIN 


(More to come next month!) 

EraseRectCtheWindow^ .portRect); 

InvalRectCtheWindow^ .portRect); 
END; (InvalContents) 


PROCEDURE DrawContents( theWindow: WindowP tr): 
BEGIN 

(Next month!) 
END; (DrawContents) 


PROCEDURE Scrol 1Contents( theW indow : WindowP tr ; dh, dv: INTEGER ); 


BEGIN 
(Next month! } 
END; (ScrollContents) 


PROCEDURE MyScro11( theControl :ControlHandle; par tCode: INTEGER) ; 


BEGIN 
(Next month!) 
END; (MyScro11) 


PROCEDURE н indowCparamPtr : XCmdP tr ); 
CONST 


minParamCount = 5; 

smal lestHeight = 100; 
smallestWidth = 100; 
-WaitNextEvent = $4860; 
-Unimplemented = $A89F; 

active = f, 

inactive = 255; 
MouseMovedEvt = $FA; 
SuspendResumeEvt = $01; 
SuspendEventMask = $1; 
ConvertScrapMask = $2; 

browseToo] = 6069; 

HCWidth = 512; 

HCHe ight = 942; 

padding = 16; 

VAR 

toolVis, patVis: BOOLEAN; 
nsgVis,fatVis: BOOLEAN; 
hasWaitNextEvent: BOOLEAN; 
inBackGround,smallScreen: BOOLEAN; 
DoneFlag,HaveEvent: BOOLEAN; 
wlop,wleft,wBottom,wRight: INTEGER; 
partCode, controlCode: INTEGER; 
largestHeight, largestWidth: INTEGER; 
dummy, charCode: INTEGER; 
screenWidth,screenHe ight: INTEGER; 
myDocWidth, myDocHe ight: INTEGER; 
eventPoint: Point; 
wRect, screenRect, dragRect: Rect; 
winSizeLimits: Rect; 
oldSize: Rect; 
newSize,dontCare: LONGINT; 
envError: 05Егг; 
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cursorRgn: RgnHandle; 
hScroll,vScroll: ControlHandle; 
whichControl: ControlHandle; 
muWindow,whichWindow: WindowPtr; 
fatBitsWindow: WindowPtr; 
HCrefresh: Str31; 
wI,wL,wB,wR,wlitle: Str255; 
toolStr,patStr,msgStr: Str255; 
widthStr,heightStr: Str255; 
myBits: BitMap; 

theEnv : SysEnvRec; 
myEvent : EventRecord; 
wRecord: WindowRecord; 
HCPort : GrafPtr; 

theOf f ScrHandle: OffScrHandle; 
theScrol Handle: ScrollHandle; 
myOf f Scr : Of fScrRecord; 
myScrol Record: Scrol Record; 


FUNCTION TrapAvailableCtNumber: INTEGER; tType: 
TrapType ): BOOLEAN; 
(Check to see if a given trap is implemented. } 
BEGIN 
TrapAvailable := NGetTrapAddress( tNumber, tType) © 
GetTrapAddress(_Unimplemented); 
END; (TrapAvai lable} 


FUNCTION CreateHScrollBar(CtheWindow:WindowPtr j 
theValue, theMin, theMax : INTEGER; 
theRefCon:LONGINT):ControlHandle; 

{Allocate and draw a horizontal scroll bar in theWindow. 

Return a controlHandle to the scroll bar.) 

VAR 

myWindowRect,hScrRect: Rect; 

BEGIN 

SetPortCtheWindow); 

myWindowRect := theWindow^.portRect; 

SetRectChScrRect,myWindowRect.left -1, 

mgWindowRect.bottom - 15, 
myWindowRect.right - 14, 
myWindowRect.bottom + 1); 

CreateHScrollBar :- NewControl(theWindow, hScrRect, 

‘MyHor iz’, TRUE, 
theValue, theMin, theMax, 


ѕсго11ВагРгос, theRef Con); 
END; (CreateHScrollBar) 


FUNCTION CreateVScrollBar(theWindow:WindowPtr Ў 
theValue, theMin, theMax : INTEGER; 
theRefCon:LONGINT):ControlHandle; 

(Allocate and draw a vertical scroll bar in theWindow. 

Return a controlHandle to the scroll bar.) 

VAR 

myWindowRect,vScrRect: Rect; 

BEGIN 

SetPortCtheWindow); 

myWindowRect := theWindow^.portRect; 

setRect(vScrRect, myWindowRect.right - 15, 

myWindowRect.top - 1, 
myWindowRect right + 1, 
myWindowRect.bottom - 14); 

CreateVScrollBar := NewControlCtheWindow, vScrRect, 

“МуУегі”, TRUE, 

theValue, theMin, theMax, 

ѕсго11ВагРгос, theRef Con); 

END; (CreateVScrollBar) | 


PROCEDURE InvalScrollCtheWindow:WindowPtr); 
(Accumulate the rectangles occupied by theWindow's 
horizontal and vertical scroll bars into the update 
region.) 
VAR 
theRect,tallRect,wideRect: Rect; 
BEGIN 
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SetPort(theWindow); 
theRect := theWindow*.portRect; 
ClipRect(theRect); 
(Accumulate tallRect, which is occupied bu the vertical 
scroll bar } 
SetRectCtallRect, theRect .right- 15, 
theRect . top, 
theRect.right, 
theRect .bottom); 
EraseRect(tal 1Rect); 
InvalRect(tal lRect); 
(Accumulate wideRect, which is occupied by the 
horizontal scroll bar } 
SetRect(wideRect, theRect. left, 
theRect .bottom- 15, 
theRect .right, 
theRect .bottom); 
EraseRect(wideRect); 
InvalRect(wideRect); 
END; (InvalScro11} 


PROCEDURE Deactivate( theW indow:WindowP tr); 

(Deactivate the scroll bars in theWindow in accordance 
with the human interface guidelines. This means we 
must erase everything enclosed by the control rec- 


tengles.) 

VAR 
theContro! : ControlHandle; 
theControlRect: Rect; 

BEGIN 


(I always title my scroll bars 'MyVert^ end ‘MyHoriz’ 
so I can easily find them by walking a window's 
control list.) 
theControl := WindowPeekCtheWindow2^.controlList; 
WHILE CtheControl © NIL) DO 
BEGIN 
IF (theControl^^.contrlTitle = ‘MyVert’) OR 
(theControl^^.contrlTitle = ‘MyHoriz’) THEN 
BEGIN 
theControlRect := theControl**.contr Rect; 
InsetRect( theControlRect, 1, 1); 
EraseRectCtheControTlRect 2; 
END; (IF) 
theControl := theContro1l^^.nextContro!; 
END; (WHILE) 
END; (Deactivate) 


PROCEDURE HiliteScrollBarsCtheWindow:WindowPtr); 

BEGIN 
(Reactivate the scroll bars; e.g., when we resume 
under MultiFinder. More next month!) 
HiliteControl(vScroll, INTEGERCactive)); 
HiliteControlChScroll, INTEGERCactive)); 

END; (HiliteScrollBars) 


PROCEDURE MoveScro] 1Bars( theWindow :WindowPtr ); 
(Call this procedure after theWindow has changed size. 
MoveScrollBars erases theWindow’s scroll bars, resizes 
them, and redraws them.) 


VAR 
myWindowRect : Rect; 
vScrRect,hScrRect: Rect; 
BEGIN 


myWindowRect := theWindow^ .portRect; 

SetRect(hScrRect, myWindowRect.left - 1, 
myWindowRect.bottom - 15, 

nyWindowRect.right - 14, 

myWindowRect.bottom + 1); 

SetRect(vScrRect,myWindowRect.right - 15, 
myWindowRect.top - 1, 
myWindowRect.right * 1, 
myWindowRect.bottom - 14); 

SetPortCtheWindow); 

ClipRect(nyW indowRect 2; 
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(Hide 1 resize the scroll bars to fit the new window 

size. 

HideControlChScro112; 

HideControlCvScro112; 

MoveControlChScro11 ,hScrRect . lef t, hScrRect . top); 

SizeControl(hScroll,ChScrRect.right - hScrRect. left), 
(hScrRect.bottom - hScrRect.top)); 

MoveControl(CvScro11] ,vScrRect . lef t, v8crRect . top); 

SizeControl(vScroll,CvScrRect.right - vScrRect left), 
(vScrRect.bottom - vScrRect.top)); 

HiliteScrollBarsCtheWindow); 

ShowControlChScro112; 

ShowControl(CvScro11); 

END; (MoveScrollBars) 


PROCEDURE Scrol1WithThumbCtheControl:ControlHandle; 
theEventPoint:Point); 
BEGIN 


(Next month!) 
END; (ScrollWithThumb) 


FUNCTION WhichDevice( thePoint:Point):GDHandle; 
(For machines that support color QuickDraw and 
multiple screens, WhichDevice figures out which screen 
thePoint is on and returns a GDHandle to that screen. 
thePoint might be where the mouse was clicked, for 
example. Thanks to Greg Marriott for this code.) 
VAR 
aDevice: GDHandle; 
foundOne: BOOLEAN; 
BEGIN 
aDevice := GetDeviceList; 
foundOne := FALSE; 
(Walk the device list until thePoint is contained 
in some device’s screen rectangle.) 
WHILE CaDevice © NIL) AND NOT foundOne DO 
BEGIN 
IF PtInRectCthePoint,aDevice^^ .gdRect) THEN 
BEGIN 
WhichDevice := aDevice; 
foundOne := TRUE; 
END; 
aDevice := a&Device^^.gdNextGD; 
END; 
END; (WhichDevice) 


FUNCTION MenuBarHeight: INTEGER; 

(Returns the height of the menubar in pixels, as read 
from the low memory global mBarHeight.) 

CONST 
mBarHeight = $ВАА; 
AR 


menuBarHeightPtr: “INTEGER; 
BEGIN 
menuBarHeightPtr := Pointer(mBarHe ight); 
MenuBarHeight := menuBarHeightPtr^; 
END; (MenuBarHe ight} 


FUNCTION OnAScreenCtheRect :Rect): BOOLEAN; 

(OnAScreen returns FALSE if all of a window's title 
bar is off the screen or if any part of it is under 
the menubar. The portRect of the window to be checked 
should be passed in theRect.) 


CONST 
titleBarHeight = 18; 
VAR 
deskRgn: RgnHandle; 
topLeft,topRight: Point; 
BEGIN 


deskRgn := GetGrayRgn; 

topLeft.v := theRect.top - titleBarHeight; 
topLeft.h := theRect.left + titleBarHeight; 
topRight.v topLeft.v; 

topRight.h := theRect.right - titleBarHeight; 
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IF ((PtInRgn(topLeft,deskRgn)) OR 
(PtInRgnCtopRight,deskRgn22) THEN 
OnAScreen := TRUE 
ELSE 
OnAScreen := FALSE; 
END; (OnAScreen) 


PROCEDURE ZoomIt(theWindow:WindowPtr;partCode:INTEGER; 
clickedWhere:Point); 
(ZoomIt supports more elegant window zooming on multiple 
Screen systems. theWindow will zoom to fill whatever 
Screen the zoom box was on when it was clicked. The 
window state toggles between original size and zoomed 
Size, as usual. Thanks to Greg Marriott for this code.) 
CONST 
titleBarHeight = 18; 


TYPE 
WStatePtr = “WStateData; 
WStateHandle = “WStatePtr; 
VAR 
oldRect,newRect: Rect; 
maxHeight: INTEGER; 
BEGIN 


oldRect := theWindow .portRect; 
IF theEnv.hasColorQD THEN 
BEGIN 
newRect := WhichDevice(clickedWhere)**.gdRect; 
IF WhichDevice(clickedWhere) = GetMainDevice THEN 
xum newRect.top := newRect.top + MenuBarHeight; 
N 
newRect :- GetGrayRgn** .rgnBBox; 
newRect. left := newRect.left + 2; 
newRect.top :- newRect.top + titleBarHeight + 2; 
newRect.right := newRect.right - 3; 
newRect.bottom := newRect.bottom - 3; 
IF NOT EqualRectColdRect,newRect) THEN 
WITH WindowPeek( theWindow)* DO 
WStateHandleCdataHandle)^^.stdState :- newRect; 
SetPortCtheWindow); 
EraseRect(whichWindow^ .portRect); 
InvalRect(whichWindow^ .portRect); 
ZoomW indow( theW indow, par tcode, FALSE); 
END; (ZoonIt) 


($1 XCmdGlue. inc) 

PROCEDURE FailCerrStr:Str255); 

(Fail returns errStr to HyperCard and exits the XCMD. 
err$tr can then be checked by inspecting HyperCard’s 
global variable “the result.” See "XCMD's for Hyper- 
Card" by Gary Bond (MIS Press, 1988) for more details. 
€ 1988 by Gary Bond 

All rights reserved. Publication rights granted MacTutor 
You may use this code for NON-COMMERCIAL purposes.) 

BEG IN 
paramPtr^.returnValue := PasToZero(errStr); 
SusBeep( 1); 
EXITCWindow); 

END; (Fail) 


PROCEDURE CheckParamCount; 


(CheckParamCount sees if the number of parameters 
passed to the XCMD matches the number expected. If 
not, we exit from the XCMD with an error message. 
See "XCMD's for НурегСага* by Gary Bond (MIS Press, 
1988) for more details. 
@ 1988 by Gary Bond 
All rights reserved. Publication rights granted MacTutor 
You may use this code for NON-COMMERCIAL purposes.) 
VAR 
numParams: INTEGER; 
BEGIN 
numParams :- paramPtr^.paramCount; 
IFCnumParams © minParamCount) THEN 
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FailC'Form: HyperWindow “Window 
Title’, top, left, bottom, right’); 
END; (CheckParamCount} 


FUNCTION GetHCVersion: Str255; 
(Return a string containing the version of HyperCard 
being used; e.g., ‘1.2’} 
BEGIN 
ZeroToPas(EvalExpr( ‘the version’ )*,GetHCVersion); 
END; (GetHCVersion) 


PROCEDURE HideWindoids; 
(Get and save the visible state of the tool, pattern, 
message and fatbits windoids; then hide them if they 
are showing.) 
VAR 
too1H,patH,msgH,fatH: Handle; 


PROCEDURE HideFatBits; 
(HyperCard does not have a built-in command for hiding 
and showing the fatbits windoid, so we have to do it 
ourselves. HideFatBits walks the window list until it 
finds a window with title “FatBits,” then hides it if 
the visible field of its WindowRecord is true. 
HideFatBits also saves the WindowPtr to the fatbits 
windoid so we can use it later (e.g., to show the 
windoid again).) 


CONST 

windowList = $906; (Low memory global location.) 
VAR 

theW indow: WindowPeek ; 

theWindowPtr: “WindowPtr; 
BEGIN 


theWindowPtr := PointerCwindowL ist); 
theWindow := WindowPeekCtheWindowPtr^); 
fatVis :- FALSE; 
WHILE CtheWindow © NIL) DO 
BEGIN 
IF C(theWindow^.titleHandle^^ = ‘FatBits’) THEN 
BEGIN 
fetBitsWindow := WindowPtrCtheWindow); 
IF (theWindow^.visible = TRUE) THEN 
BEGIN 
fatVis :- TRUE; 
HideWindowCfatBitsWindow); 
theWindow := NIL; 
END; 
END; 
IF (theWindow © NIL) THEN 
theWindow := WindowPeek( theW indow)* .nextWindow; 
END; (WHILE) 
END; (HideFatBits) 


BEGIN (HideWindoids) 
(Get visible state of windoids.) 
toolH := EvalExpr( ‘visible of tool window’): 
ZeroToPasCtoolH*, toolStr); 
DisposHandleCtoolH); 
toolVis := StrToBoolCtoolStr); 
patH := EvalExpr(C'visible of pattern window’); 
ZeroToPas(patH^ ,patStr); 
DisposHandleCpatH); 
petVis := StrToBool(patStr); 
msgH :- EvalExpr('visible of message window’): 
ZeroToPas(msgH^ , msgStr); 
DisposHandleCmsgH); | 
msgVis := StrToBool(msgStr); 
(Hide the ones that are showing.) 
HideFatBits; 
IF toolVis THEN 
SendHCMessage('hide tool window’); 
IF patVis THEN 
SendHCMessage( ‘hide pattern window’); 
IF msgVis THEN 
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SendHCMessage( ‘hide message window’); 
END; (HideWindoids) 


PROCEDURE ShowWindoids; 
(This routine assumes HideWindoids has been called 
before. ShowWindoids restores the visible state of 
the windoids to that seved by HideWindoids.) 
BEGIN 
IF toolVis THEN 
SendHCMessage( ‘show tool window’); 
IF patVis THEN 
SendHCMessage( ‘show pattern window’); 
IF msgVis THEN 
SendHCMessage( ‘show message window’); 
(As in HideWindoids, we must take care of the FatBits 
windoid ourselves. } 
IF fatVis THEN 
BEGIN 
ShowW indow( fatBitsWindow); 
SelectWindow(fatBitsWindow); 


END; 
END; (ShowWindoids) 


PROCEDURE ToggleMenuBar; 
(Set the visible of the menubar to not the visible of 
the menubar . } 
BEGIN 
IF MenuBarHeight = 0 THEN 
SendHCMessage( ‘show menubar ’ ) 
ELSE 
SendHCMessage( ‘hide menubar’); 
END; (ToggleMenuBar } 


PROCEDURE GetHCB i tMap; 
BEGIN 

(Next month!) 
END; (GetHCBitMap) 


PROCEDURE AdjustCursor ; 

(AdjustCursor changes cursorRgn to the region that 

contains the cursor. As soon as the cursor moves out of 
cursorRgn, we get an event and can change the cursor and 
cursorRgn again. cursorRgn is either the content region 
of our window or the region containing everything BUT the 
content region of our window. } 


VAR 
mouseP t : Point; 
myWinContRect: Rect; 
myWinContRgn: RgnHandle; 
deskRgn: RgnHand le; 
handHd1 : CursHand le; 
BEGIN 
Se tPor tCnyWindow); 
GetMouse(mouseP t ); 


LocalToGlobal CmousePt ); 
myWinContRgn := NewRgn; 
(Calculate the “work region” of our window, which is its 
content region minus the scroll bars and grow icon. 
This is the region within which we want the cursor to 
change to HyperCard’s browse tool, and outside of which 
we want it to be an arrow.) 
WITH WindowPeek(myW indow)* .contRgn** .rgnBBox 00 
SetRect(myWinContRect, left, 
top, 
right - 15, 
bottom - 15); 
RectRgn(myW inContRgn, myWinContRect); 
IF PtInRect(mousePt, myWinContRect) THEN 
BEGIN 
(The cursor is in the work region of our window. Set 
to browse tool.} 
handHdl := GetCursor(browseToo!); 
IF (handHdl <> NIL) THEN 
SetCursor(handHd]” “) 
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ELSE 
(Set to arrow if can’t find browse tool resource.) 
InitCursor; 

(Set the cursor region equal to our window’s work 
region.) 

SetEmptuRgn(cursorRgn); 
CopuRgn(muWinContRgn,cursorRgn); 

END 
ELSE 
BEGIN 

(The cursor is outside our window. Set to arrow.) 

InitCursor; 

(Get the current desktop region.) 

deskRgn := GetGrauRgn; 

(Set cursorRgn to the desktop region’s bounding box. 
It Із important to add the menu bar area to cursorRgn 
too. 

SetRectRgn(cursorRgn, deskRgn “.rgnBBox.left, 
deskRgn** .rgnBBox. top, 
deskRgn** .rgnBBox .r ight, 
deskRgn^ ^ .rgnBBox .bottom); 

(Punch out our window’s content region from the big 
region.) 

Dif fRgnCcursorRgn, myWinContRgn, cursorRgn 2; 

END; 
DisposeRgn(myWinContRgn); 
END; (AdjustCursor) 


BEGIN (Main Program) 


(Check the HyperCard version. Must be 1.2 or greater.) 
IF GetHCVersion < '1.2^ THEN 
FailC'Sorry, must have HyperCard 1.2 or greater.^); 
(Save thy grafPort upon entering!) 
GetPor tCHCPor >; 
(Check and reset our environment. } 
CheckParamCount ; 
FlushEventsCeveryEvent,2); 
InitCursor; 
(Find out what kind of machine we're running on.) 
envError := SysEnvirons( 1, theEnv); 
IF CenvError € noErr) THEN 
FailC'SysEnvirons call failed. ’); 
(Convert HyperTalk input parameters for use here.) 
ZeroToPasCparemPtr^ .рагатѕ (11° ,wTitle); 
ZeroToPas(paramPtr^ .рагатѕ (21° ,wT); 
ТегоТоРав(рагатРіг” .perams(3]^ ,wL); 
ZeroToPasCparamPtr^ .params(41^ ,wB); 
ZeroToPas(paramPtr~ .params[51^ ,wR2; 
wTop := INTEGERCStrToNumCwT2); 
wLeft := INTEGERCStrToNumCwL 22; 
wBottom := INTEGERCStrToNumCwB22; 
wRight := INTEGERCStrToNum(wR)); 
(If window size parameters are too small or illegal, set 
the window to a predefined minimum size.) 
IF ((wRight - wleft) < smallestWidth) THEN 
wRight := wleft + smallestWidth; 
IF ((wBottom - wlop) < smallestHeight) THEN 
wBottom := wTop + smallestHeight; 
(Make sure the user is not trying to drew the window off 
the screen or under the menubar.) 


SetRectCwRect , wLef t, wTop, wRight,wBottom); 
IF NOT OnAScreen(wRect) THEN 

FailC'You are trying to draw your window off the 

screen! ^); 
(Get the bounds of the desktop.) 
screenRect := GetGrayRgn^^.rgnBBox; 
(If we have a small screen, make a note of it so we can 
hide the card window during context switches under 
MultiFinder.) 
ZeroToPas(EvalExprC'item 3 of the screenRect^)^,widthStr); 
screenWidth := INTEGERCStrToNum(widthStr)); 
ZeroToPasCEvalExpr(C'item 4 of the screenRect^)^, 
heightStr?; 
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screenHeight := INTEGER(StrToNum(heightStr)); 
IF (screenWidth = 512) AND (screenHeight = 342) THEN 
smallScreen := TRUE 
ELSE 
smallScreen := FALSE; 
HideWindoids; 
IF MenuBarHeight > 0 THEN 
menuWasHidden := FALSE 
ELSE 
menuWasHidden TRUE; 
(This is for scrolling and will be explained next month.) 
theOffScrHandle := OffScrHandleCNewHandle 
(SizeOf (OffScrRecord))); 
IF MemError <> noErr THEN 
FailC'Out of memory. Buy more. ’); 


myDocWidth := HCWidth + padding; 
myDocHeight := HCHeight + padding; 
WITH theOffScrHandle^^ DO 
BEGIN 

(Next month!) 

D: 


GetHCB i tMap; 
(Drew the window!) 
myWindow := NewWindow(@wRecord, wRect, 
«Title, TRUE, zoomDocProc, 
WindowPtrC- 1), TRUE, 1); 
IF (nyWindow = NIL) THEN 
BEGIN 
ShowWindoids; 
FailC^Not enough memory to draw window. ’); 
END 
ELSE 
BEGIN 
(This is for scrolling. Stay tuned....) 
SetWRef ConCmyW indow, LONGINT( theOf fScrHandle)); 
InitBlitCmyWindow); 
DrawGrowIcon(myWindow); 
theScrollHandle := ScrollHandle(NewHandle 
(SizeOf CScrollRecord22); 
IF MenError « noErr THEN 
Fail('Out of memory. Buy more.^); 
(Draw horizontal and vertical scroll bars in our 
window.) 
hScroll := CreateHScrollBar(myWindow, 2,0, 
myDocWidth, 
LONG INTCtheScrollHandle)); 
vScroll :- CreateVScrollBar(myWindow, 2,0, 
myDocHe ight, 
LONGINT(theScrollHandle)); 
HiliteScrollBars(muWindow); 
DrawContents(muWindow); 
SetRect(dragRect,screenRect.left + 4, 
screenRect.top, 
ScreenRect.right - 4, 
ScreenRect.bottom - 4); 
lergestHeight := screenRect.bottom - screenRect.top; 
lergestWidth := screenRect.right - screenRect. left: 
SetRect(winSizeL imits,smallestWidth, 
smallestHeight, 
largestWidth, 
largestHeight); 
HCRefresh := ‘Go to this card’; 
cursorRgn := NewRgn; 
inBackGround := FALSE; 
DoneFlag := FALSE; 
REPEAT 
(Call WaitNextEvent, if available. Otherwise call 
GetNextEvent.) 
IF hasWaitNextEvent THEN 
HaveEvent := WaitNextEventCeveryEvent, 
myEvent, 38, cursorRgn) 
ELSE 


BEGIN 
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HaveEvent := Ge tNextEventCeveryEvent, myEvent): 
AdjustCursor ; 
END; 
IF HaveEvent THEN 
BEGIN 
IF (mnyEvent.what = app4Evt) THEN 
(Pre-process app4Evt’s fed to us by MultiFinder.) 
CASE BSR(nyEvent . message, 24) OF 
MouseMovedEvt : 
AdjustCursor ; 
SuspendResumeE vt : 
BEGIN 
myEvent.what :- activateEvt; 
(Resume event.) 
IF (BAND(nyEvent message, SuspendEventMask) © 
0) THEN 
inBackground := FALSE 
ELSE 
(Suspend event. } 
inBackground := TRUE; 
myEvent.message := LONGINT(myWindow); 
END; (SuspendResumeEvt) 
END; (CASE BSR) 
END; (IF HaveEvent) 
CASE myEvent.what OF 
mouseDown : 
BEGIN 
partCode := F indWindow(myEvent . where, whichWindow); 
IF (whichWindow = myWindow) THEN 
BEGIN 
(Deal with mouse hits to our window.) 
CASE partCode OF 
inDrag: 
BEGIN 
SelectWindow(whichWindow); (DragWindow bug) 
DragWindow(whichWindow, myEvent . where, 
dragRect); 
SendCardMessage(HCrefresh); 
AdjustCursor ; 
END; 
inGrow: 
IF StillDown THEN (GrowWindow bug) 
BEGIN 
oldSize := whichWindow^.portRect; 
newSize :- GrowWindow(whichWindow, 
myEvent where, 
winSizeLimits); 
IF (newSize <> 0) THEN 
BEGIN 
InvalScroll(whichWindow); 
SizeWindow(whichWindow, 
LOWORD(newSize), 
HIWORD(newSize),FALSE); 
InvalContents(whichWindow,oldSize); 
DrawGrowIcon(whichWindow); 
MoveScrollBars(whichWindow); 
END; (IF newSize) 
END; (IF StillDown) 
END; (inGrow) 


inZoomIn, inZoomOut : 
BEGIN 
IF (TrackBox(whichwWindow, 
myEvent.where, 
par tCode)) THEN 
BEGIN 
InvalScroll(whichWindow); 
ZoomIt(whichWindow,partCode, 
myEvent where); 
InvalContents(whichWindow, oldSize); 
DrawGrowIcon(whichWindow); 
MoveScrollBars(whichWindow); 
END; (IF TrackBox) 
END; (inZoomIn, inZoomOut) 
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inContent: 
BEGIN 
SetPort(whichWindow); 
eventPoint := muEvent.where; 
GloballoLocal(eventPoint); 
controlCode := FindControl(eventPoint, 
whichWindow, 
whichControl); 
ClipRect(whichWindow .portRect); 
IF (controlCode = inThumb) THEN 
ScrollWithThumb(whichControl,eventPoint) 
ELSE IF (controlCode © 0) THEN 
dummy := TrackControl(whichControl, 


eventPoint, 
eMyScro112; 
END; (inContent) 
inGoAway : 
BEGIN 
IF CTrackGoAway(whichWindow, myEvent.where )) 
THEN 


DoneFlag := TRUE; 
END; (inGoAway) 
END; (CASE partCode) 
END; (IF whichWindow = myWindow) 
END; (mouseDown) 
activateEvt: 
BEGIN 
IF (WindowPtr(myEvent.message) = myWindow) THEN 
BEGIN 
SetPort(muWindow); 
ClipRect(muWindow .portRect); 
DrawGrowIcon(myWindow?; 
IF inBackground THEN 
BEGIN 
(We've been sent behind another application 
under MultiFinder, so deactivate the scroll 
bars and show the menubar if it was hidden.) 
Deact ivate(myWindow) ; 
IF ѕта115сгееп THEN 
ShowHideCW indowP tr СНСРогі ), FALSE); 
IF MenuBarHeight = 0 THEN 
BEGIN 
SendHCMessage( ‘show menubar’); 
menuWasHidden := TRUE; 
END 
ELSE 
menuWasHidden := FALSE; 
END 


ELSE 
BEGIN 
(We’ve been brought to the front under Multi- 
Finder, so reactivate the scroll bars and 
hide the menubar if it was hidden before.) 
ShowHideCWindowP tr CHCPor t), TRUE); 
IF menuWasHidden THEN 
SendHCMessage( ‘hide menubar’); 
DrawControlsCmyW indow); 
HiliteScrollBars(myWindow); 
FlushEvents(CeveryEvent, ø); 
END; (IF inBackground) 
END; (IF WindowPtr) 
END; (activateEvt) 
updateEvt: 
BEGIN 
(Handle updates to our window.) 


IF (WindowPtr(myEvent.message) = myWindow) THEN 
BEGIN 
(Always do this stuff) 
SetPor t (myW indow); 
Beg inUpdate (myW indow 2; 
ClipRect(muWindow .portRect); 
DrawGrowIcon(myWindow2; 
(Always do this stuff under single Finder but 
only if in foreground under MultiF inder} 
IF NOT inBackground THEN 
BEGIN 
HiliteScrol1Bars(myWindow); 
DrawControls(myWindow ); 
AdjustCursor ; 
END; 
{Always do this stuff) 
DrewContentsCmyWindow); 
EndUpdate(myW indow?; 
END (IF myEvent.message) 
(Handle updates to HyperCard’s card window.) 
ELSE IF (WindowPtr(myEvent message) = 
WindowPtrCHCPort)) THEN 
BEGIN 
SendHCMessageCHCRef resh?; 
(Must zero out card window’s update region 
ourselves because the SendHCMessage call 
doesn’t do it, and we’1] wind up in an 
infinite loop if we don't.) 


BeginUpdate(WindowPtrCHCPort)2; 
EndUpdate(CW indowPtr CHCPor 122; 
END; (IF... ELSE) 
END; (updateEvt) 


keyDown: 
BEGIN 
IF (BitAnd(myEvent .modifiers,cmdKey) © 0) THEN 
BEGIN 
charCode := BitAnd(myEvent . message, 


char CodeMask ); 
(Pressing command-spacebar toggles the menuber.) 
IF (CHR(charCode) = ‘ ^) THEN 
ToggleMenuBar ; 
(Pressing command-W closes the window and exits 
the XCMD.) 
IF ССНЕссһагСоде) = ‘w’) THEN 
DoneFlag := True; 
END; 
END; 
END; (CASE muEvent.what) 
UNTIL (DoneFlag = True); 
(Clean up and get outta here!) 
DisposeRgn(cursorRgn); 
DisposHandleCHandleCtheOf fScrHandle)); 
DisposHandleCHandleCtheScrollHandle)); 
CloseW indow(myW indow) ; 
SendCardMessage(HCrefresh); 
ShowWindoids; 
InitCursor; 
FlushEventsCeveryEvent,2); 
(Restore thy grafPort) 
SetPor tCHCPor і); 
END; (IF myWindow. . ELSE) 
END; (Main) 
END. (Window) 27 


___________ —-—————-—-—————— — ————————— sa 
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HyperChat™ 


XCMD Corner: HyperAppleTalk, 
Part II 


Last month I introduced access to AppleTalk from Hyper- 
Card. Over the next few months I will continue this theme. 
Adding a multi-user dimension to your stacks should yield some 
very interesting and exciting results. This month I will introduce 
the Name Binding Protocol and leave you with a set of XCMDs 
that implement the more salient features of NBP. 


The Basics 

First, a quick review of the basics. Sending information 
across AppleTalk requires two mechanisms: (1) a way of identi- 
fyingentities on the network so thatany two devicescan find each 
other and (2) a "transaction protocol", some method of sending 
packets of information between any two entities. AppleTalk 
implements the first of these mechanism with the Name Binding 
Protocol (NBP) which serves as a sort of "directory assistance for 
the network. Several protocols exist for sending information 
between nodes. One of the earliest is the AppleTalk Transaction 
Protocol which manages quite well for fixed-size packages. A 
newer and more sophisticated transaction mechanism has re- 
cently been introduced by Apple and is called the AppleTalk 
Data Stream Protocol (ADSP). This protocol is straightforward 
and easy to understand, which is why I chose it for this project. 
If you must have access to the network now, I’ve implemented 
the ATP protocol which is available in the “HyperAppleTalk” 
toolkit from Apple. If you want to get a glimpse of the future of 
easy-to-program networks, I will be discussing ADSP in greater 
detail next month. 

Naming entities on the network is really a courtesy to the 
user. AppleTalk does not use names to address entities. Each 
node on the network is assigned a unique address consisting of a 
network id, a node id and a socket id. These three elements 
comprise a "phone number" of sorts. AppleTalk identifies 
entities on the network by the network address. Like the phone 
system, when you wish to call someone, you pick up the phone 
and dial that party's number. With no further intervention (until 
your party picks up the phone at the other end), the phone system 
establishes the connection and notifies your party with a ringing 
telephone. 

Because AppleTalk does not care who is at the other end of 
a connection, identifying a party becomes impossible in all but 
the smallest of network configurations (n=2). Imagine that your 
local phone directory contained the phone numbers of everyone 
in your town, but not the names associated with those phone 
numbers. From the telephone system's point of view, the phone 
book is complete, every phone number is listed in the phone 
book. From a human interface perspective, a phone book that 
listed the numbers but not the names would only be useful to if 
you didn't care who was at the other end of the line. 
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HuperCard 


The network becomes useful to the end user if some sort of 
mechanism associates entity names with network addresses. An 
entity name can be anything you choose. As an example, the 
chooser dialog allows you to enter a name for your node. 
Entering a name from the chooser, however, doesn’t mean that 
your name is automatically registered on the network. In fact, 
AppleTalk ignores this name; it is simply placed in a globally 
accessible “STR “ resource (-16906) and made available to any 
application that wants to know it. You cannot register the name 
until you receive an address from the network (Imagine that you 
are applying for a new phone number from Ma Bell. Once the 
phone number is assigned, the operator will ask you how you 
want to be registered in the phone book). 


Last Month 

Last month’s column provided a lot of nebulous code in the 
form of ADSPOpen and NBPOpen. Presenting this material 
resulted in a bit of a chicken and egg problem. I wanted to 
introduce NBP first because you already understand it in another 
form - directory assistance. In order to use NBP, you need a 
network address (if you were to look someone up in the phone 
book and not find a phone number next to their name, you might 
tend to believe that the phone book is not very useful except as 
a spelling checker). Thus, I needed to present just enough of the 
transaction side of the equation to cajole an address out of the 
network. If you compile last month’s code and run it on a system 
that has ADSP installed, about all you will get for your troubles 
is the address of a connection listener. 

When we invoked adspOpen, we first initialized some 
records that will be used by our network code. Pointers are 
indicated because HyperCard is fussy about the state of its heap. 
Our network code executes asynchronously. This technique 
allows us to get some semblance of background networking out 
of the system. In effect, we issue a request to send some 
information on the network and then goaway. When the network 
can, it will send our information and then notify us when the 
dialog completes, allowing us to move on without waiting for the 
communication to complete (which can take a long time on the 
network). 

Memory can’t be moving around on us because we have no 
idea when our information will actually be looked at by the 
network. Normally, allocating our data in handles and then 
locking down those handles during a dialog would suffice. But, 
as the saying goes, “HyperCard abhors a locked handle" and will 
unceremonioulsy unlock it if it needs to fix up its heap (once you 
get the hang of this in XCMD programming you begin to 
appreciate the beauty of it). This poses no problem since we can 
force our data not to move by allocating non-relocatable memory 
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in pointers. This is not inconsistent with Inside Macintosh, and 
it allows us to leave HyperCard’s heap in the state that it expects 
to find it (HyperCard is quite effective at handling pointers 
always pushing them to the bottom of the heap). 


Registering 

After allocating and initializing the data, we ask the network 
to consider us as a node by telling the network manager that we 
are capable of listening and responding to connection requests 
from another entity. This is just like hooking up a telephone in 
your house. Once the phone is installed and the phone company 
gives you a phone number, anytime the phone rings, you have a 
good idea that someone is trying to call you. A connection 
listener performs the same task, notifying us when another party 
calls. For the moment, let’s leave the phone ringing and get back 
to the matter of how we identify parties on the line. 

If you’ve ever applied for a telephone number you know the 
phone company will give you a number and then ask how you 
want to be listed. NBP provides just this feature on the network. 
Once you get your network address, you want to tell the network 
what name you can be reached by. This is why we do the 
adspopen before the nbpopen. First we apply for a phone 
number; if we get it we list our name in the phone book using the 
NBPRegister call to AppleTalk. 

The first element in the record tells us whether we are 
registered or not. If we are, then we probably don’t need to 
register again (would registering under several aliases serve any 
purpose?) NTEntry is of type NamesTableEntry, a special 
AppleTalk type that glues names to addresses (figure 1). To 
register an entity with the network, we must place both its internet 
address (in this case obtained from last month’s ADSPOpen 
XFCN) as well as the name into the names table entry. 


Length of Type String 


Type String 


Length of Zone String 


4 bytes — qLink 
4 bytes 
| Byte 


1 Byte 


nteData 


Figure 1. À Names Table Entry 


A registered name consists of three parts: (1) zone, (2) name 
and (3) a type. For now, the zone name is always “*” (we'll relax 
this constraint when we introduce the concept of inter network 
addressing in a future article). The name can be anything but 
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— nteAddress 


most likely you will use the name already entered in the "User 
Name" edit box in the chooser. 

This is a matter of personal choice and need. Your code 
might first check the chooser for a name and , if no name is found, 
then ask the user directly for a name. This HyperTalk script will 
register the entity using the name in the chooser and setting the 
type to “HyperPeople”: 


on MouseUp 
global myRegisteredType, myRegisteredName 


Put NBPRegisterName() into errorMessage 


if errorMessage is empty then 
— myRegisteredName now contains the same name 
— as is entered in the chooser 

else 
— report error to user 

end if 


end MouseUp 


The type is quite important. We don’t want to send 
HyperCard messages to entities that are not capable of under- 
standing them so we apply a filter to names: communicate only 
with entities that are registered as a given type. This makes 
sense, if you have two entities on the network simultaneously 
playing chess and checkers you don’t want the messages to get 
crossed (kings, for example, have dramatically different powers 
in both games). I feel the type is important, so if the user (your 
stack) doesn't choose one, I set the default to "HyperPeople". 
This is a type that is capable of reading any HyperCard message 
whether it makes sense or not! 

The rest is pretty easy to figure out. If you know the address 
of an entity then it should be an easy task to provide that address 
along with a name and a type to some xcmd that registers that 
name with the network. NBPRegisterName (Listing 1) does just 
that. The code is quite straightforward. 

The flow of information from node to node in a computer 
network is governed by the underlying physics of the network. 
Appletalk's physics may beset be described as a case of organ- 
ized chaos. I like to think of it as а "mobocratic" system, run by 
mob rule. While any two entities are passing information 
between themselves, all other entities must wait for the transac- 
tion to complete. The moment the transaction completes, the 
next entity to get its request on the wire is the winner. It may take 
several tries to be the next entity on the wire. The network's 
dynamics govern the number of retries and the time interval 
between retries; the busier the network, the more you'll have to 
wait. When you attempt to register with the net, you want to make 
sure that every entity has an opportunity to update their local copy 
of the phone book at the time you register. To make sure as many 
nodes as possible see you register, you specify aretry count. This 
is just like repeating yourself to a large gathering in hopes that 
more of the crowd will hear you. Interval specifies the time to 
wait between retries. The unit time is the "decatick". There are 
sixty ticks per second soan interval of 6 specifies a waiting period 
of one second. 

The last parameter that we pass to NBPRegisterName is the 
verify flag. If set true we want the name verified at registration 
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time. Verification is another convenience item. If any node is 
already registered with that name, you won't be able to register. 
The error message is quite explicit so you may wish to ask the 
user for another name. It's okay to have duplicate names 
registered, although this can lead to some confusion. Just as 
when you look up a Smith in the phone book, “Now which Smith 
is it that I want to call?” 

NBPUnRegisterName (listing 2) removes the registered 
name from the network. This is useful if, for example, you want 
to register under a new name. The following Script will invoke 
NBPUnRegisterName: 


on mouseUp 
global myRegisteredname, myRegisteredType 


Put NopUnRegisterName()into error 
if error is not empty then put error 
end mouseUp 


Once registered with the network, other entities can see us 
and send connection requests to us (next month). To be able to 
see other entities, we need some method of looking up other 
parties in some sort of directory. 

NBPLookupnames (Listing 3) returns a list of the network 
entities currently visible to us. This is exactly like requesting a 
phone book from the phone company, except that you will always 
get the very latest copy. One word of note: the latest copy of the 
directory may not contain ALL entities on the network, just those 
that happened to be visible and responded to the update request 
at the time that the look up was issued. 

NBPLookupNames issues a request to find all entities on the 
network. This function becomes more useful when we limit the 
process to only entities of a certain type. Since we are really only 
interested in finding entities that speak HyperTalk, we can filter 
our request to find only entities of type 'Hyperpeople' (or 
whatever type you register). 

The lookup uses three of the fields in the NBPBlock struc- 
ture that we introduced last month. EntCount is set to the number 
of entities that the function actually saw (initially set to zero 
indicating that no lookup has been performed). We place an 
upper limit of 100 (maxnodes) entities on the lookup. You can 
tune this constant to suit the individual needs of your network. 

LookupBuffer is a handle to the list of visible entities. You'll 
use NBPExtractName to pull entities out of the list. NBPLocal 
is used internally by NBP itself. You provide this buffer to NBP 
and leave it alone. NBP wants that space and doesn't want us 
fussing with it. So we don't. 

Once the lookup completes, LookupBuffer contains a 
handle to the entities that were found on the network. The 
internal structure of the lookup table is somewhat complicated by 
the intermixing of names and their addresses. To help in extract- 
ing information from the table. 

This is by no means an exhaustive list of all the capabilities 
of NBP; but since such a list would truly be exhausting, I've 
intentionally leftsome of the NBP routines out of the picture. For 
the sake of completeness, we will cover these routines as we go 
ahead with the project. Next month we will introduce the 
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AppleTalk Data Stream Protocol and provide a stack example 
that uses these routines. 

The data declarations used in these modules are defined in 
Listing 4. You should refer to last month's article for information 
on opening a connection listener. 


(Xkkkkkkkkkkkkkkkkkkkkkkkkkkýkkkkkxkxkxxx) 
(*file: NBPRegisterName.p *) 

(* *) 

(* Register a name with the *) 

(* network... *) 

(* %) 

Сх Requires that GlobalNBPData Бех) 

(* initialized and that the global *) 
(* myRegisteredName be defined *) 

(ж —əƏə—, v .-—- х) 

(Ж € 1988, Donald Koscheka %) 

(* 18-November, 1988 *) 

(ЖА11 Rights Reserved *) 

(ж *) 
(Qooeoceooceocpooccpeocpeooeoeoooecbooobcoeoeeeer) 


2321222222222 2929 222299929929 2 9: 
MPW Build Sequence 


pascal NBPRegisterName.p -o NBPRegisterName.p.o 

link -m ENTRYPOINT -rt XFCN-2003 -sn Main=NBPRegisterNamed 
NBPRegisterName .р.од 
* (Tibraries)^Interface.o д 
-0 YourStackNameHere 


XXCOOOOOOOOOIOIOOEGOOOOOGEGEOEOEÉEOXOXOCOEE ) 


($R-) 
($5 NBPRegisterName) 


UNIT Donald. Koscheka; 


6555252224222245255223222222353%98) 


INTERFACE 


635555522225222222222522223325329 


Uses 
MemTypes, QuickDraw, OSIntf, 
ToolIntf, PackIntf, HyperXCmd, 
AppleTalk, nbpxcmd; 


Procedure EntryPoint( paramPtr : XCmdPtr ); 


(Xkkkkkkkkkkkkkkkkkkkkkkkkkkkkkx) 


IMPLEMENTATION 
(ХХХ АЖК ЖЖ ХХ») 


PROCEDURE NBPRegisterName( рагатРіг: XCmdPtr 2; FORWARD; 


Procedure EntruPoint( paramPtr : XCmdPtr ); 
Begin 

NBPRegisterName( paramPtr ); 
End; 


PROCEDURE NBPRegisterName( paramPtr: XCmdPtr ); 
Q122229222222222229 2222222 22 22222229. 

* Register this entity on the network 

* using the name and type specified. 

x 

х Set the globalvariable, ‘myRegisteredName ’ 

* to the name that was registered. Note 

* that NBPOpen must be called before 
* attempting to register. 

x 

х perens[1]theName 
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* Params[2] theTupe 

* params[3]count 

х parems[4]linterval 

* params (5 ]verifyF lag 

x 

* The type is in the global myRegisteredType 

) — ————————— 

x 

* defaults are: 

*name = (from chooser ) 

xtupe = ‘HyperPeople’ 

*count = 2 

*interva 1= 8 

*verify = false; 

x 

* NOTE: will not register if a socket 

* is not open on this node! 
KXXXKKKEKKA ERA AAA AAA KAKA KEELE У 

VAR 

nbp : NBPBIkPtr; (*** our global nbp data ***) 
theName: Str255; (%%% name to register ***) 
theType: Str255; (*** type for this node ***) 
theZone: Str255; (*** always '*'(zone name) **X) 
str : Str255; (*** used in getting globs ***) 
myName: Handle; (*** used for chooser name ***) 
tempH: Handle; (*** used in getting globs ***) 
count: Byte; (*** number of retries***) 
interval: Byte; (*** wait between retires %%%) 
verify: Byte; (*** name must be unique **X) 
error: OSErr; (*** result code xxx) 

i,j : INTEGER; (*** pascal string length ***) 
Mpb : MPPParamBlock; (*** param block ***) 


($I XCMDGlue. Inc ) 


BEGIN 
error := noErr; 
nbp := NIL; 


(*** Retrieve pointer to our NBPData ***) 
tempH := GetGlobalC ‘GLOBALNBPDATA’ ); 


(*** Convert the string to a handle ***) 
IF CtempH © NIL) THEN 
BEGIN 
HLock( tempH ); 
ZeroToPas( tempH^, Str 2; 
nbp := NBPBIkPtrC StrToLongC Str 22; 
HUnlock( tempH 2; 
DisposHendleC tempH ); 
END; 


IF € nbp © NIL ) AND € NOT nbp^.Registered ) THEN 


BEGIN 


(*** Before registering, we need ***} 

(*** the internet address stored in ***) 

(*** string form in a container  ***) 
tempH :- GetGlobal( ‘mySocketListener’ ); 


(*** Convert the string to a network ***) 
(*** address Clonginteger ) xxx) 

IF С tempH € NIL ) THEN 

BEGIN 

HLock( tempH ); 

ZeroToPas( tempH^, Str ); 


прр“ .NTEntry.nteAddress:= AddrBlock(StrToLong(CStr22; 


HUnlock( tempH ); 
DisposHandle( tempH 2; 
END; 

nbp^.NTEntry.qLink := NIL; 


WITH ParamPtr^ 00 
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BEGIN 

(*** If user specifies а name ***} 

(*** ке/11 use it, otherwise use ***) 

(*** the name in the Chooser ***) 

IF € params[1] = nil ) OR Cparams[1]** = Ø) THEN 
BEGIN (*** Get name from chooser %%%) 
myName := GetResource( ‘STR ', NODE.NAME ); 


IF myName € NIL THEN 
BlockMoveC myName*, 6theName[2], 
GetHandleSizeC myName ) ); 
END 
ELSE 
BEGIN (*** Use name passed in **X) 
HLockC params[1] ); 
ZeroToPas( parems[1]^, theName ); 
HUnlock( paramst1] 2; 
END; 


(*** IF the user provides a type ***) 
(*** use it otherwise, use the ***} 
(*** default type xxx) 
IF Cparams(2) = nil) OR Cparams(2]1^^ = Ø) THEN 
theType := ‘HyperPeople’ 
ELSE 
BEGIN 
HLockC рагатѕ [2] ); 
ZeroloPas( params[2]*, theType ); 
HUnlockC params[2] ); 
END; 


(*** AppleTalk, Zone Name must ***) 
(*** be '*^ (this zone) xxx) 
theZone := '*'; 


(*** Put the name away in the ***) 

(*** entity data part of the names ***) 
(*** table entry. Inside Macintosh ххх) 
(*** vol II p.321 (figure 13) depicts ***) 
(*** the structure of a names table ххх) 
(*** element. Note that the first ххх) 
(*** byte in the nteData array is used***) 
(*** internally. We put the chars ***) 
(*** away starting at array offset 2 ***) 


і := 2; 


FOR j := 0 TO Length( theName ) DO 

BEGIN 
пор“ .NTEntru.nteData[i) := theName[j]; 
і := i+ 1; 

END; 


(*** The type gets tacked to the ***) 
(*** end of the names string. This ***} 
(*** is not the same as the concat **X) 
(*** function, each string keeps  **X) 
(*** its length byte. ххх) 


FOR j := Ø TO Length( theType 2 DO 
BEGIN 
nbp^.NTEntry.nteData[i] := TheTupe[j); 
i:= i+] 
END; 
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(*** Likewise, theZone gets tacked ***) 
(*** to the end of the type string ***) 
FOR j := Ø TO LengthC theZone ) DO 
BEGIN 
nbp* .NTEntry.nteDatalil] := TheZone[j]; 
i := 1+ l; 
END; 


(*** Number of times to register ***) 


@ The Best of MacTutor, Vol. 5 


IF params[3] <> NIL THEN 

BEGIN 
HLock( рагатѕ [3] ); 
ZeroToPas( params(3]*, str ); 


count := INTEGERC StrToLong( Str )); 


HUnlock€ Params[3] ); 
END 
ELSE 

count := 2; 


(*** 10Х ticks between requests***) 
IF params(4] © NIL THEN 
BEGIN 

HLockC params[4] ); 

ZeroToPasC params[4]*, str ); 


interval := INTEGERC StrToLong( Str 2); 


HUnlockC Params[4] ); 
END 
ELSE 

Interval := 8; 


(*** If the last parameter is true ххх) 
(*** make sure that the name is ***) 
(*** not already in use xxx} 
IF рагатѕ (5 ] © NIL THEN 
BEGIN 
HLock( рагатѕ [5] ); 
ZeroToPas( params[5]*, str ); 
verify := BYTECstrToNumC str )); 
HUnlockC Params[5] ); 
END 
ELSE 
verifu := 0; 
END; 


(*** Now set up an make the cal] *xx*) 
(*** to register this enitity ***) 
Mpb.ioCompletion := NIL; 
Mpb.interval ‘= interval; 
Mpb . count := count; 
Mpb.entityPtr := @nbp .NTEntru; 
Mpb.verifyFlag := verify; 


error := PRegisterName( @Mpb, SYNC); 


IF error = noErr THEN 
BEGIN 


paramPtr^.returnValue := PasToZero( ”” ); 


(*** As a courtesy to the system, ***) 
(*** save name off in a global **x*) 
(*** this is an easy way to get ***) 
(*** name from the chooser Xxx) 
nbp^.Registered := TRUE; 


SetGlobalC ‘MyRegisteredName’,PasToZero( theName)); 


END 
ELSE 


paramPtr* .returnValue :=PasToZero(numToStr(longint(error))); 


END; 
END; 


END. 
Listing 1. NBPRegisterNane 


CoXooooooooeoocooeooeoooeocooooeexo) 


(*file: NBPUnRegisterName.p *) 
(ж х) 

(* Remove name from the network*) 
(* if that name if currentlu *) 
(* registered. *) 

(* *) 


(* Requires GlobalNBPData be *) 
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(* initialized and that global *) 
(* myRegisteredName be defined *) 
(* —— t) 

(* @ 1988, Donald Koscheka *) 
(*8-December, 1988 *) 

(*A11 Rights Reserved *) 

(* *) 
(ЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ Ж) 


(YXXXXXXXX1X1X1X1XXXXXXXXXXXXXXXXXXX 
MPW Build Sequence 


pascal NBPUnRegisterName.p -o NBPUnRegisterName.p.o 


link -m ENTRYPOINT -rt XFCN=2004 -sn Main=NBPUnRegisterNamed 


NBPUnReg isterName .p.od 
* (Vibraries)"Interface.o à 
-0 yourStackNameHere 


X xoXoXcooocoooocoooocooooooopooooee) 


($R-) 
($S NBPUnRegisterName) 


UNIT Donald Ковсһека: 


(ХХХ ХХХ ЖЖ) 
INTERFACE 


655552422544242244222222222333439 


Uses 
MemTypes, QuickDraw, OSIntf, 
ToolIntf, PackIntf, HyperXCmd, 
AppleTalk, nbpxcmd; 


Procedure EntryPoint( paramPtr : XCmdPtr ); 


(YKXXX1X£7X1X1XXXXXXXXXXXXXXXXXXXXXXX) 


IMPLEMENTATION 
(XXXXXXXXXXXXXX5XXXXXXXXXXXXXXXXX) 


PROCEDURE NBPUnRegisterName( paramPtr: XCmdPtr ); FORWARD; 


Procedure EntruPoint( paramPtr : XCmdPtr ); 
Begin 

NBPUnRegisterName( paramPtr ); 
End; 


PROCEDURE NBPUnRegisterName( paramPtr: XCmdPtr ); 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 

х UnRegister this entitu оп the network 
using the information alreadu contained 
in the NBP data block. 


Upon successful] completion, clear the 
global variable, ‘myRegisteredName’ and 
set the state of the “Registered” flag 
for this connection to FALSE. 


3 3 9 м к % % м 


XXXX3XXXXX11XXXXXXXXXX1XXXXKEXXKXKK) 
VAR 


nbp : NBPBIkPtr; (*** our global nbp data ***} 
tempH: Handle; (*** used in getting globs ***} 


error: OSErr; (*** result code | ххх) 
Mpb : MPPParamBlock; (%%% param block ***) 
Str : Str255; 


($1 XCM0Glue.Inc ) 


BEGIN 
error := noErr; 
nbp := NIL; 


(*** Retrieve pointer to our NBPData ***) 
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tempH := GetGlobalC “GLOBALNBPDATA ); 


(*** Convert the string to a handle ***) 
IF CtempH © NIL) THEN 
BEGIN 
HLock( tempH 2; 
ТегоТоРав( tempH^, Str ); 
nbp := NBPBIkPtrC StrToLongC Str 2); 
HUnlockC tempH 2; 
DisposHandleC tempH ); 
END; 


IF € nbp © NIL 2 AND С nbp^.Registered ) THEN 
BEGIN 
Mpb.ioCompletion := NIL; 
Mpb.entituPtr := @nbp* .NTEntry.nteDatal2]; 
error := PRemoveName( @Mpb, SYNC); 


IF error = noErr THEN 

BEGIN 

peremPtr^.returnValue := PasToZero( ‘’ ); 

(*** As a courtesy to the system,  ***) 

(*** save name off in a global ***) 

(*** this is an easy way to get ***) 

(*** name from the chooser xxx) 

nbp^.Registered := FALSE; 

SetGlobalC 'MyRegisteredName^, PasToZeroC ”” ) D); 

END 

ELSE 

peremPtr^.returnValue :- 
PesToZero(numToStrClongintCerror 22); 


END; 
END. 


Listing 2. NBPUnRegisterNane 


(YXYXXXXX1XXXX1XXXKXXXXXXXXX1X1XXX1XXXX) 


(*file: NBPLookup.p *) 
(ж * 


(* params[1] = theTupe *) 

(* params[2] = theZone *) 

(* params[3] = number to look up*) 
(* params[4] = count *) 


(* params[5] = interval *) 
(* *) 

(* Entitu names are returned *) 
(* ina list and sent to the *) 
(ж HyperCard global: *) 

(* ‘NBPLookUpTable’ *) 

(* *) 

(* ReturnValue is set to the *) 
(* result of the lookup *) 


(* х) 

(* —À—aso D, —— ə,—əƏ *) 

(* Defaults: x) 

(* ж) 

(х name = ‘=’ С All names) х) 
(ж type = ‘=’ C all types ) *) 
(* zone = '*' (current zone)*) 


(х nun = 100 С 100 names) *) 
(* count= 2 ( do 3 lookups) *) 
(* interval= 4( decaticks) *) 
(ж ж) 

Сх ---------%) 

(* € 1988, Donald Koscheka *) 
(ЖА11 Rights Reserved *) 


(* х) 
(* 05-Nov-88 *) 
%-----() 


65255312555 53225352525222252222222 
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(XXXXxXxxxxx*xxxxxxxxxxxxxtkxxxxxxx 
MPW Build Sequence 


pascal NBPLookupNames.p -o NBPLookupNames.p.o 
link -m ENTRYPOINT -rt XFCN22005 -sn Main=NBPLookupNamesd 
NBPLookupNames .p .0d 
* (libraries) ^Interface.o 9 
* (plibraries)^PasLib.o д 
-0 yourStackNameHere 


XXXXXXXXXxxXxxx*xxx**xxxxxxxxxxxxzxxx*) 


($R-} 
($S NaPLookupNames) 


UNIT Donald_Koscheka; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У 


INTERFACE 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖХЖЖЖЖХЖХЖЖЖЖЖЖЖ У 


Uses 
МепТурев, QuickDraw, OSIntf, 
ToolIntf, PackIntf, HyperXCmd, 
AppleTalk, nbpxcmd; 


Procedure EntryPoint( paramPtr : XCmdPtr ); 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖХЖЖХЖХЖЖХЖЖЖЖЖЖЖЖЖ) 


IMPLEMENTATION 
(ЖЖЖЖ) 


CONST 
DEFAULT_ERR= 128; (*** some sort of mem error ххх) 


ТҮРЕ 
Str255Ptr = ^Str255; 


PROCEDURE NBPLookupNames( paramPtr: XCmdPtr 2; FORWARD; 


Procedure EntryPoint( paramPtr : XCmdPtr ); 
Begin 

NBPLookupNemesC paramPtr ); 
End; 


PROCEDURE NBPLookupNames( paramPtr: XCmdPtr ); 
(Qoocoooooeoeoeeeeeeoeex 

* Lookup entities of the 

* requested type and zone 

x (up to num elements): 

* 


ЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ)) 
VAR 
tempH : Handle; 
nbp : NBPBIkPtr; 
EntSize : LongInt; 
i,j cnt, err, 
intr, total, 


num : INTEGER; 

str : $tr255; 

ent : NamesTableEntry; 
Mpb : MPPParamBlock; 
theType, 


theZone : Str255; 
($1 XCMDGlue.Inc } 


FUNCTION ReturnNames: Handle; 
(Xxx Xxxxxxxxxxxxxx xxx xxxxxxxxxx 
* Return a list of entities as 


* found in the lookup table 
x 


XXXXXXXXXXX1X51XXXXXX1XX1XXXXXXXX) 
VAR 
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eAddr : AddrBlock; (*** Needed bu the extract 
newHand: Handle; (*** current entitu namektup 
а Handle; (*** Lookup Data to return 
xxx 

ret : Stringl1]; (*** newline after each ent 
oldSize: LongInt; (*** Previous size of table 
е LongInt; (*** size іо add to table 
xxx 


i : INTEGER; (*** loop control variable ххх) 


ххх) 
xxx) 


ххх) 
ххх) 


theEnt : EntityName; (*** names from the names table***) 


BEGIN 

oldSize := 1; 

theTable := NewHandleC oldSize ); 

IF theTable € NIL THEN 

BEGIN 
theTable^^ := 0; (*** set theTable to EMPTY**X) 
ret[0) := CHRC 1 ); 
ret[1] := СНЕС 13); 


FOR i := 1 TO nbp^.EntCount DO 
BEGIN 
(*** extract name i from the list ***)} 
WITH nbp^ DO 
BEGIN 
HLockC LookUpBuffer ); 
err := NBPExtract( LookUpBuffer^, 
total, i, theEnt, eAddr); 
HUnlock( LookUpBuffer ); 
END; 


IF err = noErr THEN 

BEGIN 

(*** each line in the list gets***) 
(*** entities name and type ***) 
Str := “2, 


Str := Concat( theEnt.objStr, 
',’,theEnt.typeStr,ret); 

newHand:= PasToZero( Str ); 

newSize:=GetHandleSize(newHand); 

OldSize:=GetHandleSize(theTable); 

SetHandleSizeCtheTable,newSize*oldSize); 

BlockMoveCnewHand^, 
PtrCORDCtheTable^2*o1dSize- 1), 
NewS ize); 

DisposHandle(C newHand ); 

END; 

END; (*** FOR i := 1 to Total ***) 


(*** make sure return string is null **X) 
(*** terminated or hypercard will have***} 
(*** a fit xxx) 
END; (*** IF theTable <> NIL ***} 
ReturnNames := theTable; 
END; 


BEGIN 


err := noErr; 


(*** Retrieve pointer to our NBPData ***) 
tempH := GetGlobalC ‘GLOBALNBPDATA’ ); 


(*** Convert the string to a handle **x) 
IF CtempH © NIL) THEN 
BEGIN 
HLock( tempH 2; 
ZeroToPas( tempH^, Str ); 
nbp := NBPBIkPtrC StrToLong( Str 2); 
HUnlockC tempH 2; 
DisposHandleC tempH 2; 
END; 
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IF € nbp O NIL ) THEN(*** okay to lookup ***) 
BEGIN 
WITH paramPtr^ DO 
BEGIN 
IF params{1] = NIL THEN 
theType := ‘=’ 
ELSE 
BEGIN 
HLockC params[1) ); 
ГегоТоРаѕ( params[1]^, theType ); 
HUnlockC params[1] ); 


END; 

IF params[2] = NIL THEN 
theZone := ‘*’ 

ELSE 

BEGIN 


HLockC params[2] ); 
ZeroloPas( params[2]^, theZone ); 
HUnlockC рагатѕ [2] ); 

END; 


IF рагатѕ [3] € NIL THEN 
BEGIN 
HLockC params[3] ); 
ТегоТоРав( params[3]*, Str ); 
num := INTEGERCStrToNumC Str ) ); 
HUnlockC params[3] ); 
END 
ELSE 
num := MAXNODES; 


IF рагатѕ [4] © NIL THEN 
BECIN 
HLockC params[4] ); 
ZeroToPas( params[4]*, Str ); 
cnt := INTEGERCStrToNumC Str ) ); 
HUnlockC params[4] ); 
END 
ELSE 
cnt := 2; 


IF рагатѕ [5] O NIL THEN 

BEGIN 
HLockC params[5] ); 
ZeroToPasC params[5]^, Str ); 
intr := INTEGERC StrToNumC Str ) ); 
HUnlockC params[5] ); 

END 

ELSE 
intr := 4; 

END; (*** with paramPtr^ ххх) 


(*** Concatenate the name, type and zone string 
ent.nteData[2] := CHR(1); 
ent.nteData[3] := ‘=’; 
i := 4; 


FOR j := Ø TO Length( theType ) DO 
BEGIN 

ent.nteData[i] := TheTypetj]; 

i := 1 + 1; 
END; 


(*** Likewise, theZone gets tacked***) 
(*** to the end of the type string***) 
FOR j := Ø TO Length( theZone ) DO 
BEGIN 

ent .nteDatali] := TheZone[j]; 

i := i+ l; 
END; 


(*** The lookup data is stored as a handle in 


ххх) 


ххх) 


(*** our NBPBlock. Since а пен lookup supercedes***) 


(*** the previous data, delete previous Cif any)***) 
IF nbp* .LookupBuffer <> NIL THEN 
BEGIN 
HUnlockC nbp^.LookUpBuffer ); 
DisposHendleC nbp^.LookUpBuffer ); 
END; 


nbp^.EntCount := 0; 
EntSize := sizeof( NamesTableEntry ); 
пор” .LookUpBuffer:= NewHandleC num * EntSize ); 


IF nbp^.LookUpBuffer «» NIL THEN 
BEGIN 
MoveHHiC nbp^.LookUpBuffer ); 
HLockC nbp*.LookUpBuffer ); 


WITH mpb DO 

BEGIN 
EntityPtr := &ent.nteData[2]; 
retBuffPtr := nbp^.LookUpBuffer^; 


retBuffSize:= INTEGERC EntSize*num ); 
maxToGet := num; 
interval := intr; 
count := cnt; 


END; (*** with mpb ххх) 
err := PLookUpNameC @Mpb, SYNC ), 


IF err = noErr THEN 

BEGIN 

nbp^.EntCount := Mpb.numGotten; 

SetGlobal( ‘NBPLookupTable’,ReturnNames ); 

paramPtr* .returnValue := PasToZero( ‘’ ); 

END 

ELSE 

paramPtr* .returnValue := 
PasToZeroCnumToStrClongintCerr 22); 


HUnlockC nbp^.LookUpBuffer ); 
END 
ELSE 
err := DEFAULT.ERR; (*** no room in the heap? ***) 
END; 
END; 
END. 


Listing 3. NBPLookUpNenes 
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(E2232 3225%39 933553599999 39325 59> У 
(*file: NBPXCMD.p ж) 

(* *) 

(* Constant and type declaration*) 
(* file for nop xcmds *) 

(Ж c X) 

(* € Donald Koscheka *) 
(*6-October, 1988  *) 

(*A1] Rights Reserved 5) 

(ж х) 

(* — À ao , %dP j *) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЕЖЖЖЖЖЖЖЖЖЖЖЖЖ) 


UNIT NBPXCMD ; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖ у 


INTERFACE 


(YXKYX1XX1X1XXXX1X1XXKXXXXXX1XXXXXKXXXEKE) 


USES Memtypes, QuickDraw, OSIntf, ToolIntf, AppleTalk; 
CONST 


ASYNC = TRUE; 

SYNC = FALSE; 

NODE.NAME = -16096; (Сх STR resource name from Chooser 
х) 

MAXNODES = 100; (% maximum 8 of nodes for zone *) 
NBPLSIZE = 120; (% size of a local buffer for МР *) 
NN = 30; (* 8 of names in lookup table*) 

ENTITYSIZE = 110;  (* size of entity in lookupbuffer *) 


TYPE 
Str31 = String(31]; 


NBPBIkPtr = ^NBPBlock; 

NBPBlock = RECORD 

Registered : BOOLEAN; (* true = registered *) 

EntCount : INTEGER; (* # of entities visible х) 
LookUpBuffer: Handle; (* lookup buffer *) 

NTEntry : NamesTableEntry; (% entry in names table Ж) 
NBPLocal : arrau[1..NBPLSIZE] of Char;(* used by NBP *) 
END; 

END. 


Listing 4. Definitions needed for the XFCNs 
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HyperChat™ 
AppleTalk DSP Part Ш 


Before I start with this month’s column, I would like to 
explain the change in this month’s byline: 

Prior to joining Arthur Young in New York, I worked for 
Apple Computer Inc in Cupertino. When our daughter, Colleen, 
was born a year ago, my wife and I agreed that we would move 
back east so that Colleen would have an opportunity to get to 
know both her paternal and maternal grandparents who live in the 
NY area. My challenge was to find an interesting programming 
job, specializing on the Macintosh, in the New York area. My 
first inclination was to see whether Apple would be interested in 
putting someone with my experience in the field, perhaps to 
support large accounts in their Macintosh projects. 

Unfortunately, this proved to be a dead end. I was told that 
Apple needed engineers with IBM experience, Macintosh expe- 
rience was not needed nor even welcome outside of Cupertino. 
In my despair, I realized that I was going to have to look for a 
position outside of Apple. 

Interestingly enough, my job search never went farther than 
the pages of MacTutor. Arthur Young and Company, a large 
accounting firm based in New York, placed an ad in MacTutor 
inviting interested parties to interview with the firm’s Macintosh 
development group. 

Arthur Young is one of the world’s largest users of the 
Macintosh; their reputation for ingenious uses of the Macintosh 
and their professionalism spurred me to respond to the ad. As 
you can tell by the byline, the rest is history. 

The lesson: Whether you have a product to sell or you have 
an interesting programming solution to share with the rest of us, 
MacTutor is the best forum for reaching the Mac Programming 
community. 


Now this month's column: 

If you've been following this column for the last several 
months, you know that we are building an interface to AppleTalk 
іп HyperCard. In the first installment, I introduced some network 
basics as well as a few routines to open and close the AppleTalk 
Data Stream Protocol (ADSP) driver. The second installment 
featured an interface to the Name Binding Protocol (NBP). 

This month, I would like to present the bulk of the routines 
that will be needed to support ADSP from Hypercard. Due to 
space considerations, I will present the Hypercard XCMD glue 
for these routines in next month's issue. I apologize for the 
seemingly capricious way that I have broken up this information, 
but I could easily fill a book with this material - programming the 
network is fun, and I have a lot of information to cover. 

Listing 1 contains the file "ADSPXCMP.P" which contains 
the data definitions for the adsp interface. Listing 2 contains the 
file "XCMDADSP.INC". This file should be included in your 
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XCMD immediately following the “XCMDGlue.Inc” declara- 
tion. It contains the underlying code used in our appleTalk 
interface. 

ADSP is a very elegant protocol that can best be described 
in terms of the phone system. In order to call someone, you first 
look up their number. Next you dial the phone and wait for a 
connection. Once the connection is established, you begin 
talking. 

I chose the AppleTalk Data Stream Protocol (ADSP) as the 
transport mechanism because of its intuitive programming 
model. We will use ADSP to send HyperCard messages between 
stacks that are running on separate machines. These machines 
will refer to each other as the “remote end”, that is, the other side 
of the connection. 

ADSP isa new protocol that provides “peer to peer" commu- 
nications on the network. Any two entities that communicate 
with each other share the same capabilities. Contrast this with the 
"server-client" model where clients request information and 
servers provide it. Peer to peer models have the advantage of 
being bidirectional. Either party may request or provide informa- 
tion. In fact, one can easily model the “client/server” protocol 
using peer-to-peer communications. 

The routines in listing 2 support four parts of an ADSP 
interface: (1) Looking through the phone book for a number or 
name (NBPGetAddress and NBPGetName), (2) Hangup on 
someone (DSPKillData, DSPDisconnect and DSPHangUp), (3) 
Dial and connect (DSPAddConnection, DSPCreate) and (4) Talk 
to another party (DSPTalk). In case you've noticed that I have 
not provided any code for listening, I will present ADSPListen in 
its entirety next month. Listening on the network, like listening 
in general, is the more difficult part of communications. One of 
the reasons for presenting the routines in Listing 2 before present- 
ing the XCMDs that use them is that ADSPListen shares a 
number of these routines with other XCMDs. A review of the first 
two issues of this column might help you follow Listing 2 a little 
better. 


Let your fingers do the walking 

Transaction protocols such as ADSP expect to work with 
network addresses. Both NBPGetAddress and NBPGetName 
provide the name binding support needed by ADSP to determine 
the address of an entity given that entity's name and vice versa. 

NBPGetAddress and NBPGetName let your fingers do the 
walking. Given a currently visible name, NBPGetAddress will 
return the “phone number". Conversely, NBPGetName returns 
the name given the address. The latter is useful when a remote 
entity is calling in. Both routines expect to have a list of network 
visible entities available in the lookupBuffer field of the nbp data 
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block. If this field is empty, then no lookup has been done. No 
name/address binding can occur until a lookup is performed. A 
good rule of thumb is to invoke NBPLookupNames prior to 
calling anyone on the network to make sure that the names table 
is valid. Periodic updates to the names table are also a good idea. 
A good time to perform the periodic lookup is when you receive 
an incoming call from an entity that NBPGetNames can’t find in 
the lookup table (the lookup table is “‘stale”). 


Operator, Get me Mr. Winkler 

In order to call another entity, you must establish a connec- 
tion with that entity. Typically, you call an entity by name. This 
is equivalent to an old-fashioned telephone exchange where you 
ring up the operator and said something to the effect, “Hello, 
operator, this is Dennis Mitchell. Can you connect me to Mr. 
Wilson?” 

DSPCreate acts as the operator and will attempt to establish 
a connection. 

First we allocate room for the connection data in the heap via 
a newPtr call. If we get the connection block (cb) we go ahead 
an initialize its fields. The only space we must allocate a priori 
is room for the input and output buffers. All the other fields get 
set to NIL or 0. 

DSPAddConnection puts the connection block into the 
linked list. This is standard linked list code and allows us to 
maintain more than one connection at a time. 

We interface to ADSP via parameter block I/O. The parame- 
ter block is stored in the dspPB field of the connection block. 
Parameter block I/O is the lowest programming level that the 
application programmer usually interfaces with devices on the 
Macintosh. Managers such as the file manager and the print 
manager come with an extra layer of “glue” that shields the 
programmer from the parameter block. At the time of this 
writing, no such glue existed for ADSP, you interface with it via 
the parameter block. 

All calls to adsp are made via the PBControl call with the 
csCode field set to the operation to perform. In the case of 
DSPCreate, we wish to establish a connection with the remote 
end. The csCode for establishing a connection is dspInit. Inter- 
facing to AppleTalk via parameter blocks is Apple’s preferred 
method and, while it takes a little getting used to, it’s not really 
all that hard to follow. One hint: the csCode field of the parameter 
block will tell you what operation is being requested. 


Sorry, Bad Connection 

DSPHangUp undoes the work of DSPCreate. It first re- 
quests ADSP to remove, or tear down, the connection. This 
process will notify the remote end that the connection is going 
down. The dspRemove request is performed synchronously as 
we must wait for it to complete before we can deallocate the data 
used by the connection. 

DSPDisconnect removes the connection from our list of 
connections, sends a message to Hypercard advising of the 
disconnected line and then calls DSP kill data to remove the data 
associated with this connection. You may not want to send a 
disconnect notice to Hypercard so either set remName to NIL or 
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simply remove that portion of the code. 

Once the connection is removed from the connection list, 
DSPKillData deallocates all of the data associated with a connec- 
tion. The connection data includes an input buffer, an output 
buffer and an attention buffer. We do not use the attention buffer 
in this incarnation. 


Don’t you ever stop talking? 

The last routine of note in listing 2 is DSPTalk. This isa 
simple routine that allows you to send data over an established 
connection. Note that the connection block is already assumed 
to be valid, some other routine must have performed the cross- 
check, as we shall see next month. 

Sending information is remarkably simple in ADSP: first 
copy the data to an output buffer in the connection’s data block. 
Next, issue a dspWrite request to the remote end. Here, the 
transmission is performed asynchronously. We can let the 
transmission take as long as it needs allowing control of the 
system to be almost instantaneously returned to Hypercard. Next 
month I will show you how to detect the completion of a 
transmission. 


Support Routines 

In addition to the ADSP routines, XCMDADSP includes а 
number of routines that are needed throughout the interface: 

Retrievedata accepts the name of a hypercard global con- 
tainer and converts its contents to a long integer. It is used to 
retrieve the pointers to the NBP and ADSP data blocks created by 
NBPOpen and ADSPOpen respectively. 

StringtoShort converts a zero-terminated string to a pascal 
integer type. Hypercard parameters are passed as string repre- 
sentation of numbers. Several parameters to the ADSP routines 
require integer arguments. 

StrCmp compares two pascal-style strings. It is used by the 
NBP getAddress procedure to match the input string to the strings 
in the lookuptable. When the entity name matches the input 
string, the ensuing address can easily be extracted from the table 
(the “phone book" ). 


This is a lot of code to digest in one month but once you start 
writing stacks that can interact with each other, I think you'll find 
that staying with me for one more month is well worth the effort. 
Moreover, I believe that ADSP represents the type of network 
interface that takes the pain and drudgery out of networking. A 
lot of the code that I have presented here can be used outside of 
Hypercard. I hope you give ADSP a try, you might find its full 
capabilities quite intriguing! 

Next month: We wrap up our initial interface to AppleTalk 
with four XFCNS: ADSPCall, ADSPHangup, ADSPTalk, 
ADSPListen. 


Listing 1: 
6555534441323225442222222222222222245222422222222252222222222 
(*file: ADSPxcmd .p х) 

(*version: .018 х) 


(* *) 
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(& —əə>-,— .—— F e x) 
(* By: Donald Koscheka and Nancy Rosenberg 5) 


(* Date: 1-Feb-88 х) 
(* @Copyright 1988, Apple Computer, Inc. *) 
(*A1] Rights Reserved *) 
(* ж) 
(Хх — ə— ən ж) 
СЖ Modification Historu *) 
(ж —ÀcÁə a pÁLmÑ———əəƏ— ə ə>ə —— . .  — x) 
(* Date | Bul Description x) 
(х — ə — > х) 
(ж 1-Ғер-88 | DK | file created *) 


(* 13-May-88 | DK | Added user area to connection record*) 

(* 13-May-88 | DK | Added File Transfer Record*) 
(= ES ый 
Cooopoooooocoooocooconoonoooonpeoopboooroooroooroooooo p xoooooooooor) 


UNIT adspxcmd; 
INTERFACE 


USES Memtypes, QuickDraw, OSIntf, ToolIntf, AppleTalk, ADSP; 
CONST 


ASYNC - TRUE; 

SYNC = FALSE; 

(*** connection mode status **X) 
NOP = 0; 

REQ = 1; 

ACK = 2; 

EST = 3; 


GLOBALNBPDATA= 28400; 
GLOBALDSPDATA= 29337; 
GLOBALSKTDATA= 21644; 
DEFAULT_ERROR= 23220; 
NO.ERROR = 22416; 


МЕМ. ERROR - 31830; 

NBPLSIZE = 120; 

ATPBSIZE = 578;  ( standard size of “transaction” buffer ) 
INTERVAL = 20; 

{ default retry interval 60 ticks=10 secs.) 

RETRY = 3; (retry count = 3: total = 3 * 60 = 30 secs.) 
PORTBUSE = $291; 

SPCONFIG = $1FB; 

CLOSE_OK =й; 

RECEIVING = 1; 

CLOSE_NOW = 2; 

NEWLINE = $00; 


( inserted after each entru in the zone info table) 


alalkVars = $208; 

( pointer to appletalk vars, aka aBusVars, mppVars) 
sysABridge = $19; 

( Node address of a bridge [byte] 

sysNetNum = $14; ( This node’s network number [word]} 


(fee File Transfer Protocol XXXxxxxixixxx) 


NO_FORK = 0; (Currently not sending any data} 
DATA_FORK = 1; (Currently sending the data fork of file) 
RESOURCE_FORK= 2; ( Currently sending resource fork of file) 
FINDER_FORK = 3; (Currently sending finder bytes of file} 
FILE.NOT.READY = 0; (Кой ready to send the file yet) 


FILE_READY = 1; ( ready to receive the file} 


(ЖЖЖЖЖЖЖЖЖХАЖЖЖЖЖЖЖЖЖААЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖАЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖ) 
(* As long as you’re asking... х) 
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(* х) 

(* The following data blocks reference memory pointers rather 
than handles. This is *) 

(* not an intentionally egregious use of the memory manager 
but rather a way to *) 

(* insure that all of the data in the connection block is 
non-relocatable since *) 

(* ADSP runs asynchronously, the data must always be presented 
to ADSP. Hypercard *) 

(* doesn’t seem to mind non-rels and tends to do a fairly good 
job of concatenating*) 

(х them low in the heap СНурегсага is no slouch when it comes 
to nonrels either, so *) 

(* we're just piggybacking our pointers on top of the large 
nonrel area at the start*) 


(* of the Hypercard application heap). ,a ne fait rien.*) 
Qoeceocooeoeooooocooooocgdooooooocooooooeoooooooooooobooeoooooonoee) 


TYPE 


LIntPtr - ^LongInt; 
IntPtr = ^INTEGER; 


CBP tr = “Connection; 

Connection = Packed Record 
next : CBPtr; ( pointer to next block in the list) 
last: CBPtr; ( pointer to the last block in the list) 
ccbRef : Integer; ( reference number for this connection ) 
mode : Integer; 
( set to EST if the connection is open & ready} 
adr : AddrBlock; 
( address of remote end (NIL if not connected)) 
msg : Handle; ( callback message for incoming data) 
sendQ : Ptr; 
( buffer for sending to remote connection end ) 
recvQ : Ptr; 
( buffer for receiving from remote connection) 
attn: Ptr; ( buffer for attention messages) 
outBuf : Handle; ( where the outgoing data is placed) 
inBuf : Handle; ( where the input data goes) 


attnBuf : Handle; ( where the attention data goes} 
remName : Handle; ( entity name of the remote end) 
ccb : TRCCB; ( pointer to connection control block) 


attnPB : DSPParamBlock; 

( attention messages parameter block ) 

dspPB : DSPParamBlock; 

( connection param block for this connection) 
user : Handle; ( place for user def ined data.) 


End; 

ADSPPtr - ^ADSPBlock; 

ADSPBlock Packed Record ( ADSP protocol data) 
dspRefNum : Integer; ( driver refnum for ADSP ) 
ccbref : Integer; ( ccbRefNum connection listener) 


addr : AddrBlock; ( socket address of this entity) 

ends : CBPtr; ( 1151 of established connections) 

ccb : TRCCB; (ріг to listener connectn contr! blck} 
pb : DSPParamB lock; 

( parameter block for connection listener} 


checkPoint : Integer; (set if we’re in a callback now) 
oldSelf : Byte; ( old state of the self-send flag} 
pad : Byte; ( keep em even, steven} 

End; 

NBPPtr = ^NBPBlock; 


NBPBlock = Packed Record 
Registered : Integer; 
( true if we are already registered ) 
EntCount : Integer; ( number of entities visible) 
LookUpBuf fer: Handle; ( handle to the lookup buffer) 
NTEntry : NemesTableEntry; ( entry into names table) 
NBPLocal : array[1..NBPLSIZE] of char; 
( used internally by NBP } 

END; 
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FXPtr = “FXRecord; 


FXRecord = Packed Record ( File Transfer Record.) 
Status : Integer; ( state of the current connection) 
Fork : Integer; ( current for being transferred) 
FilePtr : Ptr; ( Data buffer for the transfer) 
refNum  : Integer; (reference id to the file ) 
Name : Str255; ( file name 
io : peremBlockRec; ( io parameter block for the i/o) 
END; 
End. 


Listing 2: 


(UOUEEXEEOOOOEOEOEEEEEEEEEEXEEX XXX XXX) 


(*file: XCndGlue . Inc X) 
(* *) 
(* Support routines for АОЅР %) 
(* Hypercard interface. *) 
(* — *) 

(* By: Donald Koscheka ж) 
(* Date: 9-Jan-89 *) 
(* All Rights Reserved x) 
(* х) 
(% ————— х) 


(ЖЖЖЖЖЖЖАЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЕЖЖЖЖЖЖЖЖЖХ) 


(COOEEEEGEEEEEEEXEEEXEXEXGEEXEXEXXXXEXXX) 
(* x) 


x Miscellaneous support routines x) 
* x 


(Ххх ххх ХА Ххх ххх хх) 


FUNCTION RetrieveDataC containerName : Str255 ): LongInt; 
(Y33353 3555553 КЕКЕК 

* Given the name of a Hypercerd 

* global container, return the 

* data stored there as a long 

* [nteger. 


Container data is a handle 

to the contents of a global 
container. Theses contents 
should contain the string 
representation of а long integer 
which we convert to pascal 
longInt . 


3 2 9 х »* x »* * x 


* Since containerData is а 
ж copy of the data, we must 


* dispose of it afterwards. 
EKKEKKKEKEKAAARAKAEAEKA ELEY ) 


VAR 
containerData: Handle; 
1ongStr : $tr255; 
BEGIN 


ContainerData := GetGlobal( containerName ); 


(***If the container is not empty, convert it***) 
IF (ContainerData € NIL) AND CContainerData^ © NIL) THEN 
BEGIN 
HLockC ContainerData 2); 
ZeroToPas( ContainerData*, longStr ); 
RetrieveData := StrToLong( longStr ); 
HUnlockC ContainerData ); 
DisposHandleC ContainerData 2; 
END; 
END; 


FUNCTION StringToShort( str : 


(Ххх ххх хх 


х Given а pointer to a “С^ 
* string, convert the number 


Ptr 2: INTEGER; 
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* to an integer and return 
* it to the caller 
жж У 
VAR 

tempStr 
BEGIN 

ZeroToPas( str, tempStr ); 

StringloShort := Integer(StrToNum(tempStr)); 
END; 


: Str255; 


Function StrCmp( si, s2 : String ): Boolean; 
(XxxxxxxtXxkxixkixk xk kx ERE 


* Given two strings, return true 
* if they match exactly, false 


* otherwise 
ххх) 
VAR 
i,j : Integer; 
matching : Boolean; 
BEGIN 


matching := true; 
i := Іледегі s1[0] 2; (*** number of characters in str ***) 
j := Integer( 82101 2; (*** as well as comparison string***) 
IF i = j THEN (*** if not same len, not same string***) 
WHILE i » 2 DO 
BEGIN 
WHILE matching DO 
IF sili] © s2[i] THEN (*** strings don’t match***) 


BEGIN 
matching := false; 
i := 0; 
END, 
122-7 = 1; 
END; 
StrCmp := matching; 
END; 


PROCEDURE p2cStr( myPtr : Ptr ); 
(Ххх ххх ХХХ ХХХ 

* Convert a pascal string to a 

ж “с” string in place 

KXKKAKAKAKA AKA KAKA A KAKA EKA KE AE) 


VAR 
i : LongInt; 
ePtr: Ptr; 
BEGIN 
FOR i := 0 to myPtr^ DO 
BEGIN 
aPtr := PointerC ORDC myPtr ) + 1); 
myPtr^ := aPtr^; 
myPtr := aPtr; 
END; 
myPtr := PointerC ОВОС myPtr ) - 1); 
myPtr* := 0; 
END; 


PROCEDURE TrashHandle( inH : Handle ); 
(*23352535 5355353 KERR ERE EES 
* Unlock the input handle 
* and deallocate it 
XEX*XEXXXEXEXXEXEXEXXEX) 
BEGIN 
IF inH © NIL THEN 
BEGIN 
HUnlock( inH 2; 
DisposHandle( inH 2; 
END; 
END; 


( Coopoooooooeceeeeeeeeeeeeeeeeeeoeooeeeeer) 
(* х) 
(ж Routines to access entities in the *) 
(ж names table х) 
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FUNCTION NBPGetAddress(name : Ptr ): AddrBlock; 


(Жжжж ЖЖЖЖ 


x 


x 
x 
x 
x 


Given the name of an entity 
walk through the names table 
for the name and return 

the address if found, NIL 


otherwise 
* 


ЖЖЖЖ) 


VAR 
error : Integer; 
nbp : NBPPtr; 
found : Boolean; 
eName : EntityName; 
eAddr : AddrBlock; 
who : Integer; 
str : StringPtr; 
pName : Str255; 
BEGIN 
found := FALSE; 
who = 1; 
nbp := NBPPtrC RetrieveDataC ‘GLOBALNBPDATA’ ) ); 


IF Спор © NIL ) AND (nbp^.LookUpBuffer © NIL) THEN 
BEGIN 

str := StringPtr( 6eName.objStr ); 

ZeroToPas( name, pName ); 


NBPGetAddress.aNet = 0; 
NBPGetAddress.aNode := 0; 
NBPGetAddress.aSocket := Ø; 


HLock( Handle(nbp^.LookUpBuffer) ); 
IF (nbp^.EntCount > 0) THEN 
REPEAT 
error := NBPExtract(Ptr(nbp* .LookUpBuf fer^), 


IF error = noErr THEN 
BEGIN 
found := StringEqual( str^, pName ); 
IF found THEN 
NBPGetAddress := eAddr 
ELSE 
who := who + 1; 
IF (who > nbp*.EntCount) THEN found := TRUE; 
END 
ELSE 
found := TRUE; 
UNTIL found; 
HUnlock( Handle(nbp .LookUpBuffer) ); 
END; 


пор” .EntCount, who, eName , eAddr ); 


END; 


FUNCTION NBPGetNameC addr : AddrBlock ) : Handle; 
6255253932599 553 5559593595 or 


x 
x 
x 
x 
x 
x 


Given the address of an entity, 
walk through the names table 
searching for the address and 
return the name of the entity, 
nil if not 


xdoooocoeoceooococeeeee eer) 


VAR 
error : Integer; 
nbp : NBPPtr; 
done  : Boolean; 
eName : EntityName; 
eAddr : AddrBlock; 
who : Integer; 
yourName: Handle; 
BEGIN 
done := FALSE; 
who шз; 
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uourName:= NIL; 
nbp := NBPPtr( RetrieveDataC ‘GLOBALNBPDATA’ ) ); 


IF (nbp € NIL) AND (nbp^.LookUpBuffer «> NIL) THEN 
BEGIN 
HLock( nbp^.LookUpBuffer ); 
IF (nbp^.EntCount > 0) THEN 
REPEAT 
error := NBPExtract( 
nbp^ .LookUpBuff er^ ,nbp^ .EntCount , who, eName, eAddr ); 
IF error = noErr THEN 
BEGIN 
IF LongIntCaddr) = LongIntCeAddr ) THEN 
yourName :- PasToZero( eName.objStr ) 
ELSE 
who := who + Í; 


IF Cwho > nbp*.EntCount) THEN 


done := TRUE; 
END 
ELSE 
done := TRUE; 


UNTIL (done) OR CyourName <> NIL ); 


HUnlock( nbp* .LookUpBuffer ); 


END; 
NBPGetName := yourName; 

END; 
(жка) 
(* *) 
(* Routines to hangup and tear down a *) 
(* connection х) 
x x 


(жж) 


PROCEDURE DSPKillDataC cb : cbPtr ); 

А2 255222 22222252222222521434239 
(* Either we could not allocate enough*) 
(* memory or the connection would not *) 
(* initialize, dump all allocated data*) 
(* *) 
(* The input parameter, cb, points to *) 
(* the block that we want to kill *) 


(* *) 
Qoooooooooopboooooeoeoooeeoocobopoeonec) 
BEGIN 
IF cb «> NIL THEN 
WITH со: DO 
BEGIN 


(*** could not allocate or initialize ***) 
IF sendQ € NIL THEN DisposPtr( sendQ 2% 
IF recvQ © NIL THEN DisposPtr( recvQ ); 
IF attn © NIL THEN DisposPtr( attn ); 


TrashHandle( remName); 
TrashHandle( msg 2) 
TrashHandleC inBuf ); 
TreshHendleC outBuf ); 
TrashHandie( attnBuf ); 


DisposPtrC Ptr( cb ) ); 
END; 
END; 


PROCEDURE DSPDisConnect( сп: 
(FREER EERE RARER RARER AERA EK 

* Tear down an ADSP connection, 
* deallocate the memory and remove 


x the entity from the connection list. 
XXXXXXXXXX XX OX EXE XXX XX) 


CBPtr ); 


VAR 
nb, lb : CBPtr; 
dpb : dspPeremBlock; 
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tH : Handle; 


BEGIN 
IF cn © NIL THEN 
BEGIN 
IF cn^.remName <> NIL THEN 
BEGIN 
SetGlobalC ‘ADSPCaller’, cn^.remName 2; 
SendCardMessage( ‘HungUp’); 
END; 


(*** remove connection from connection list***) 
IF cn = adsp*.ends THEN (* special case: cn = first *) 
BEGIN 

adsp^.ends := cn^.next; 

nb := cn^.next; 


IF nb © NIL THEN nb*. lest := NIL; 
END 
ELSE 
BEGIN 
nb := cn^.next; 
lb := cn*. last; 
IF nb © NIL THEN nb*. last := 1b; 
IF ЛЬ © NIL THEN 1b^.next := nb; 
END; 
DSPKillData( cn ); 
END; 


END; 
FUNCTION DSPHangUp( cn : CBPtr ):0SErr; 


5555 452525252222222222522 22222252. 


* Hangup the line on requested 
connection end 


IN: 
pointer to the connection’s block 
handle to the data to send 


є x 3 мж HM € 


555322232 2222222222222222222222223 


VAR 
myPB : DSPParamB lock; 


BEGIN 
IF cn © NIL THEN (*** If connection exists, tear down***) 
BEGIN 
WITH myPB DO 


BEGIN 
ioCRefNum := adsp^.dspRefNum; 
ccbRefNum := cn^.ccbRef ; 
csCode := dspRemove; 
abort m =] 


(*** Hangup sunchronouslu because the state of the 
connection is about to go ballistic ***) 
END; 
DSPHangup := PBControlC @myPB, SYNC ); 
DSPDisConnect( cn ); 
END; 
END; 


(YXYX351333X53X55XX5X3335X5XX3355X555X5XX5) 
(* х) 
(ж Routines to install а connection *) 
(* and call a remote partu. * 

(* х) 
(ookooooceooecoecoeecopeeoeecoopceo|eoeererg) 


PROCEDURE DSPAddConnectionC cb : CBPtr 2; 


(Xxxoooceoeeeoeooceoceoeee EE 


* If we have а good connection, we can 
* go ahead and put it into the connection 
* list. It is either the first item in 
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x 
* 


the list or we append it to the end by 
traversing the list to find the last item 


XXXXXXXXXX*XEXEXEXXXXEXEXEXXX) 


VAR 


nb, lb : CBPtr; 


BEGIN 


END; 


пр := adsp* .ends; 


IF cb © NIL THEN 
IF nb = NIL THEN 


adsp^.ends := cb 
ELSE 
BEGIN 
WHILE nb © NIL DO (*** walk to end of list***} 
BEGIN 
lb := nb; 
nb := nb*.next; 
END; 
lb^.next := cb; 
cb*.next := NIL; 
cb*. last := 16; 
END; 

FUNCTION DSPCreateC addr :AddrBlock; 
inBufSiz, 
outBufSiz, 
retry, 
interval : Integer; 


message : Handle 2: CBPtr; 


Ы 525552222222 E KG EE 


* Creates an ADSP connection, 
* adds it to the connection list, 
x 
x 
* IN: 
* addr : address of the entity 
* inBufSiz, 
* outBufSiz 
x : size of the buffers 
* retry : number of times to 
х retru the open 
Ж interval : 10Х{іскѕ time to wait 
ы between retries 
* mess : callback message 
* 
* OUT: 
* CBPtr : return a pointer to 
f the connection, NIL if 
* connection not inited 
* 
жж) 
VAR 

error : Integer; 

siz : LongInt; 

cb : CBPtr; 

nbp : NBPPtr; 


havelt : BOOLEAN; 


BEGIN 


cb := CBPtr( NewPtr( SizeOf( Connection ) )); 
IF cb © NIL THEN 


WITH cb DO (*** Allocate connection’s structures***) 
BEGIN 
ccbRef := 0; 
msg = NIL; 
lest := NIL; 
next := NIL; 
adr := addr; (*** address of the remote end ***) 
inBuf := NIL; (*** no data received get**X) 
outBuf := NIL; (*** no data sent yet ***) 
attnBuf := NIL; (*** no attention message...***) 
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mode := NOP; (*** connection not established***) END; 

sendQ NewPtr( LongInt(outBufSiz) ); DSPCreate := cb; 
recvQ NewPtr( LongIntCinBufSiz) ); END; 

attn := NewPtr( attnBufSize ); 


Бы 2522522 522 522222222 


(*** (3) Initialize the connection end **x*) (* *) 
IF (sendQONIL) AND (recvQONIL) AND (attnONIL) THEN (* Routines to send information over * 
BEGIN (* the wire. *) 
IF message © NIL THEN (х +} 
BEGIN (YYXXXXX131XX131XXXX151XXXXXXXXXXXXXXXXXXXXXXX) 
siz := GetHandleSize( message ); 
msg :- NewHandle( siz ); FUNCTION DSPTalkC cn : CBPtr; bufH : Handle ):0SErr; 
BlockMove( message^ , msg^, siz ); (кж 
END; * Send the data to the requested 
* connection end 
WITH attnPB DO * IN: pointer to the connection’s block 
BEGIN x handle to the data to send 
userRout ine := NIL; x 
ioResult = 1; (xxx mark it as busy***) KKK KKK HK KKK KK KK IK k } 
END; VAR 
Hsiz : LongInt; 
ccb.userFlags := 0; 
BEGIN 
WITH dspPB DO (** Initialize the connection end **) (*** (1) Copy the data into a local buffer 55%) 
BEGIN cn^.outBuf := NIL; (*** assume we won’t allocate handle ***) 
csCode :» dspInit; 
ccbPtr іш @cb*.ccb; IF bufH © NIL THEN 
userRoutine := NIL; BEGIN 
ioCRef num := adsp^.dspRefNum; HSiz := GetHandleSizeC bufH 2; 
ioCompletion:= NIL; сп” .outBuf := NewHandle(C HSiz ); 
sendQSize ‚= outBufSiz; END; 
sendQueue ‚= sendQ; 
recvQueue ‚= recvQ; IF cn^.outBuf © NIL THEN 
recvQSize := inBufSiz; BEGIN 
attnPtr ‘= attn; MoveHHi( cn*.outBuf ); 
localSocket := adsp*.addr .aSocket; HLock( cn*.outBuf ); 
END; BlockMoveC bufH^, cn^.outBuf^, HSiz 2; 


error := PBControl( @cb*.dspPB, SYNC ); 
(*** (2) Send the data to the other end ***) 


IF error = noErr THEN WITH cn^.dspPB DO 
(*** Add connection to list if init ok ***) BEGIN 
BEGIN ioCompletion:= NIL; 
ccbRef := dspPB.ccbRefNum; ioCRefNum := adsp*.dspRefNum; 
DSPAddConnection€ cb )j -------- csCode := dspWrite; 
ccbRefNum := cn*.ccbRef; 
END reqCount := Integer( HSiz ); 
ELSE dataPtr ‚= cn^.outBuf ^; 
DSPKillDataC cb ); eom = 1; 
flush = Í; 
END ( IF data allocated OK ) END; 
ELSE( data did not allocate or connection did not DSPTalk := PBControlC @cn*.dspPB, ASYNC ); = 
initialize ) END; (әч! 
DSPKillDetaC cb ); END; у 
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HyperChat™ 


XCMD Corner: Window Scrollbars 


In Last Month’s Episode... 

Last month I showed you how to write an event-driven 
XCMD that displays a normal Macintosh window on top of 
HyperCard. I discussed some interesting human interface issues 
that come up when you do this, and I demonstrated how to 
communicate with HyperCard from an XCMD in order to do 
window updates and other “human interface maintenance” tasks. 
I also used the XCMD as a springboard for illustrating more 
general techniques, including how to be MultiFinder aware, how 
to do cursor tracking under MultiFinder, and how to cope 
elegantly with multiple-screen environments. Finally, I gave the 
window scroll bars that didn’t work, and I promised to “breathe 
life into them” this month, which I will do by adding code to the 
XCMD that takes a “snapshot” of the current card and displays 
it in the window. We can then scroll around and admire the 
snapshot until we either get bored, learn about scrolling, or both! 


Scroll Bars! 
The scroll bars are here! 
The scroll bars are here! 
Why should I care? 
People have been scrolling for years.... 

Yes, but few people have taken the time and effort to explain 
scrolling to neophyte Mac programmers, who must either figure 
it out themselves, copy code from someone else, or avoid it 
completely. Why is this? I have a simple theory: People are 
ashamed of their scrolling code. In fact, some people might be 
afraid of their scrolling code. Scrolling code is ugly. It consists 
of gobs of source riddled with special cases and questionable 
algorithms. Nobody has found an elegant way to do it, so nobody 
wants to show their version of it to anybody else. 

On top of all this, scrolling is implemented differently 
depending on the type of document being scrolled, be it bitmap- 
ped graphics, object-oriented graphics, text, icon lists, etc. While 
the basic rules stay the same, the special cases change and often 
multiply. Therefore, learning everything there is to know about 
scrolling is a daunting task indeed. 

Icertainly don’t know everything about scrolling, but I know 
enough to get you started if you’ ve never done it before, and I can 
touch on a few fundamentals that may help you improve your 
scrolling code if you’ ve written some already. In this article I will 
show how to scroll bitmapped graphics documents, including 
how to set up and manage an offscreen bitmap for fast, flicker- 
free scrolling. I will assume we have a static document that 
cannot be edited or moved around inside its window. I leave these 
more challenging cases as proverbial exercises for the reader. 

If you haven't done so already, read the Control Manager 
chapter of Inside Macintosh, Volume I so I don't have to explain 
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the Toolbox software behind controls. I will repeat some of the 
general material in that chapter, but I will not go into the data 
structures and other nuts-and-bolts information because there 
just isn't room for it here. 

Those of you who have never written scrolling code stand to 
benefit the most because, like I said, annotated examples of it 
don't exactly abound. Unfortunately, the only thing worse than 
implementing scroll bars is explaining how the code works, so 
bear with me because there is a lot to cover and most of it is very 
dry. My plan is to first discuss the anatomy and arithmetic of 
scroll bars, then talk about all the special cases and implementa- 
tion details. Finally, as a special bonus, I will describe how to set 
up and maintain an offscreen bitmap for a document you are 
scrolling. 

This isaton of material, but remember: No pain, no gain; no 
guts, no glory. Onward! 


The Anatomy of Scroll Bars 
Most of this section is a review of material in the Control 
Manager chapter of Inside Macintosh, Volume I, and of the 
Scroll Bars specification in Apple's Human Interface Guide- 
lines: The Apple Desktop Interface (Addison-Wesley, 1987) I 
repeat it here in order to fix terms and to lend continuity to the 
article. 


Scroll bars consist of five parts, as illustrated in Figure 1. 
These parts are the up arrow, page up region, thumb, page down 
region, and down arrow. The names are the same for a horizontal 
scroll bar, with the left end being “up.” 

=== Joe's Window 
up arrow 


page up region 
thumb 


page down region —- D 


The up and down arrows scroll the document arbitrarily 
small but equal distances in their respective directions. If you are 
scrolling text, for example, the arrows might scroll it one line at 
a time. If you are scrolling graphics, you might shift your 
document 5 to 10 pixels at a time depending on how fast and 
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smooth you want the scrolling to be. In any event, the distance 
scrolled remains constant, regardless of window size. 

Page up and page down scroll the document one “page” or 
“windowful” at a time. Mostapplications scroll slightly less than 
a windowful so users can keep track of where they are as they 
scroll through long documents. Obviously, the distance scrolled 
varies with window size. 

Finally, the thumb can be dragged anywhere in the scroll bar; 
when it is released, the application scrolls to the corresponding 
position in the document. The distance scrolled depends only on 
the thumb displacement and is independent of window size. 

Scroll bars can be either active, unhighlighted, or inactive. 
A scroll bar is active when the window that owns it is active and 
the document can be scrolled in the scroll bar's direction; active 
scroll bars are illustrated in Figure 2a. 


=== Joe's Disk 


Software Project Toolkit 


The White Bison Project 


If the owning window is active but the document cannot be 
scrolled (e.g., when the entire document is visible in the win- 
dow), then the scroll bars are unhighlighted, and they appear as 
in Figure 2b. 


Software Project Toolkit 


The White Bison Project 


Figure 2b 
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Finally, if the owning window is inactive, the scroll bars 
must be inactive and look like those in Figure 2c. 


14 items 18,975K іп disk 197K ; 


Software Project Toolkit 


The White Bison Project 


Figure 2c 
Scroll Bar Arithmetic 

You will find it mucheasierto write scrolling code if you can 
express scroll bar behavior in simple algebraic form. Good 
scrolling code, like QuickDraw, stands on a firm mathematical 
foundation. Building this foundation is best accomplished by 
drawing some pictures. 

Figure 3 shows a large Macintosh window anda long, skinny 
document we wish to scroll. I have labeled important dimensions 
on the diagram; some of these will figure prominently in our 


algebraic expression of scrolling behavior. 


k— ——— doc Width 


dvGraf 


: visHeight 


—————— docHeight ———— —— — "a, 


viswidth 
dhGraf 


Figure 3 
I define docWidth and docHeight as the width and height of 
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the document’s rectangle; visWidth and visHeight as the width 
and height of the portion of the document visible in the window; 
and dhGraf and dvGraf as the distances the document has been 
scrolled in the horizontal and vertical directions, respectively. 
dhGraf = dvGraf = 0 when the top left corners of the document 
and the window's portRect coincide, and both of these variables 
increase as the document moves up and to the left relative to the 
window; i.e., as we scroll down and to the right. The units for all 
these variables are pixels. 

These are all the variables we need to express the 
document's position relative to the window. But we also need to 
express the thumbs’ positions relative to the top (or bottom) of the 
scroll bars. The thumbs are moved by changing their control 
values; if we find the algebraic link between the control values 
and the variables described above, life will be great. 

Inside Macintosh tells us that every control has predefined 
minimum and maximum values and a current value; this infor- 
mation is stored in the ControlRecord data structure for that 
control, and is initialized by us when we create the control with 
NewControl. The current value, of course, is where the thumb 
happens to be relative to the minimum and maximum values, so 
our first decision is: what should the minimum and maximum 
values be? Although you can choose a scheme as convoluted as 
you desire, I'll choose zero for the minimums, and doc Width and 
docHeight as the maximums of the horizontal and vertical scroll 
bars, respectively. I'll also initialize both current values (thumbs) 
to zero, placing us at the top left corner of the document. 


The Golden Ratio of Scrolling 

From now on, I'll simplify the discussion by considering 
only the vertical scroll bar; the exact same principles apply to the 
horizontal one. Here's a quick exercise: dvGraf limits how far we 
can scroll up and down in the document. It's smallest possible 
value is zero, when we are at the top of the document. What's the 
largest value dvGraf can have? docHeight? No! The correct 
answer is docHeight - visHeight, because once the bottom of the 
document is visible above the top of the horizontal scroll bar, we 
don't need to scroll down any more. 

The largest value the thumb can have, however, is do- 
cHeight. At the top and bottom of the document, then, we have 
the following relationships: 


Top:  dvGraf = 0 
vThumb = 0 


Bottom: dvGraf = docHeight - visHeight 
vThumb = docHeight 


This suggests an important proportional relationship we 
must preserve as we scroll through the document: 
vThumb = CdvGref * docHeight) / 
CdocHeight - visHeight) 
As a check, substituting dvGraf = 0 into the above equation 


gives vThumb - 0, and substituting dvGraf = docHeight - 
visHeight gives vThumb = docHeight. I call this the Golden 
Ratio of Scrolling, just because lots of high-falutin' proportions 
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in mathematics are called the Golden Ratio of something or 
another. My Golden Ratio will ensure that you scroll your 
documents the way users expect you to. 

We now have enough mathematical background to imple- 
ment scroll bars. Before diving into the code, however, let's learn 
about offscreen bitmaps and blitting, which will make our 
scrolling smooth and fast. 


Bits, Blits, and CopyBits 

You may have noticed that some applications have smooth, 
flicker-free scrolling while others have the choppy, flicker-ful 
variety. What you are witnessing is the almost total supremacy of 
CopyBits and blitting over ScrollRect in the scrolling arena. The 
basic idea is that CopyBits lets you blast an offscreen copy of 
your document to the screen immediately after you scroll (this is 
called blitting), while ScrollRect waits around for update events 
to be handled. On the downside, blitting takes a lot more memory, 
and you really have to be clever when you try to use it with large 
documents or large displays. 

Scott Knaster gives a great explanation of blitting and 
offscreen bitmaps in his book Macintosh Programming Secrets 
(Addison-Wesley, 1988); I'm going to condense a similar dis- 
cussion into a much smaller space here. If you get confused, 
check out pages 190-208 of Scott's book. 

Let's take a concrete example. My XCMD takes a snapshot 
of HyperCard's card window, adds 16 pixels of white padding to 
the right and bottom edges, and stores the picture into an 
offscreen bitmap, which is just a nonrelocatable buffer in mem- 
ory with a bitmap's structure. We will use NewPtr to allocate 
memory for the bitmap, so we need to determine how many bytes 
of memory we need. The card window is 342 pixels tall by 512 
wide; adding 16 to both dimensions gives a rectangle 358 x 528 
pixels. First we calculate rowBytes using Knaster's incredibly 
bizarre but effective formula: 


rowBytes = (((pict.right - pict.left - D div 16) + 1) * 2 
= (((528 - Ø - 1) div 16) + 1) * 2 
= 66 
From here on out things are much more intuitive: 
bufferSize = (pict.bottom - pict.top) * rowButes 
= 358 * 66 
= 23628 bytes 
So to create our bitmap we make the following calls: 
VAR myBits: BitMap; 


myBits.rowBytes := 66; 
myBits.baseAddr := NewPtr(23628); 
( do error checking, of course ) 


SetRect(myBits.bounds, 0,0, 528,358); | 
All that's leftis to copy a picture of the card window into the 


bitmap; see procedure GetHCBitMap in the source listing for 
details. 


Scrolling and Blitting 
Now that our offscreen bitmap is set up, it's time link it to the 
scroll bars. This is where that great eclectic concept of blitting 
comes in. 
Quick and efficient blitting is not accomplished by blasting 
the entire offscreen image to the screen and clipping to the 
portRect (minus the scroll bars) of the target window. If you did 
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that and Bill Atkinson saw your code, he would say, “No, no, no, 
that's dumb.” 

Instead, Bill would suggest that you copy a piece of the 
offscreen image just big enough to fit in your window. Assuming 
you are scrolling around and want to see different pieces of the 
image, you need a scheme for deciding which piece to copy. This 
is where the concept of a blit rectangle comes in. 

(By the way, Bill Atkinson probably knows how to com- 
press an arbitrary 512 by 342 pixel bitmap into three bits, so he 
might suggest something even more efficient. If he does, listen 
carefully and write it all down, because you'll never figure it out 
yourself.) 

A blit rectangle is an image of the onscreen window's 
portRect (minus the scroll bars) superimposed on the offscreen 
bitmap; see Figure 4. It is visWidth wide by visHei ght tall. If you 
resize the onscreen window, you resize the blit rectangle accord- 
ingly, except that the blit rectangle can never be larger than the 
offscreen bitmap or you will blast the random garbage that lies 
beyond into your onscreen window. Similarly, when you scroll 
the onscreen window, you slide the blit rectangle the appropriate 
distance and direction, always staying within the bounding 
rectangle of the offscreen bitmap. 


e doan Dirk э 


blit rectangle 


onscreen window 


offscreen bitmap 
(entire document) 


Figure 4 

After you have resized or moved the blit rectangle as 
described above, you copy its contents to the onscreen window 
with CopyBits. In the case of scrolling, the copy is performed 
immediately, but in the cases of zooming or resizing, the copy is 
performed when update events are handled. Summarizing, the 
sequence of steps is: 

° Scroll onscreen window and move thumb 

° Slide blit rectangle proper distance and direction over 
offscreen bitmap (don’t let it slide off, however!) 

° сору contents of blit rectangle to onscreen window 
immediately 

-ОГ- 

° Zoom or resize onscreen window 

° zoom or resize blit rectangle, up to size of offscreen 
bitmap 
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° сору contents of blit rectangle to onscreen window at 
update time 

That's it for the concepts behind scrolling and blitting. Now 
we can look at the code and see how this stuff is done in practice, 
complete with refCon data structures, special cases, and other 
nasty ugliness. 


First, a Pair of Data Structures 

In this section and the ones that follow, I’m going to walk 
through the code that was stubbed out of last month’s listing. For 
your convenience, however, I’m including the entire source of 
the Window XCMD. 

Starting with the TYPE declarations, notice the two data 
structures Г ve defined, OffScrRecord and ScrollRecord (wonder 
no more, newcomers to Mac programming, you’ re about to find 
out what on earth refCon fields are used for! ). OffScrRecord 
contains window-specific information, including a pointer to the 
grafPort containing the offscreen bitmap for the window, the 
width and height of the document in the bitmap, the current size 
of the blit rectangle, and current scroll state of the document. A 
handle to this information is stored in the window’s refCon field, 
and I continually update the OffScrRecord via this handle in my 
scrolling code. 

ScrollRecord contains two rather cryptic fields that I use for 
human interface purposes; I'll explain them later. In this pro- 
gram, I create only one ScrollRecord on the heap and share it 
among all my scroll bars. You’ll soon understand why this is 
possible. 

Allocating space on the heap for these data structures is 
accomplished with a parentheses-rich Pascal statement of the 
form: 

myBlobHandle := BlobHand]e(NewHand1e(Size0f (BlobRecord))); 


How to Initialize Scroll Bars 

Let's skip down to the main program, and ГІП touch on the 
procedures used for initializing the scroll bars and offscreen 
bitmap. 

After we've put the owning window on the heap, we go 
ahead and initialize its scroll bars. First we allocate space for the 
ScrollRecord, because if there's no room for it we have to quit. 
Assuming there is space, we grab our handle to it and initialize 
the ScrollRecord's fields. Again, I'll get to what they mean in а 
minute. 

Next we call CreateHScrollBar and CreateVScrollBar, 
functions of my own design that allocate and return Control- 
Handles to the respective scroll bars for a given window. I 
recommend you name your controls as shown because it helps 
out in debugging. 

HiliteScrollBars is called next; it checks the size of the 
window against the size of the document and unhighlights the 
appropriate scroll bar if the window is bigger in a given direction 
(see Figure 2b). Otherwise it checks the scrolled state of the 
document (given by dvGraf and dhGraf; see Figure 3) and 
positions the thumbs accordingly. Notice the use of the Golden 
Ratio. Notice also that HiliteScrollBars is called whenever: 

* the window is made active 
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° the window is resized or zoomed 

° the window is updated 

After the window and scroll bars are drawn, DrawContents 
blasts the bits inside the blitrectangle to the screen. The offscreen 
bitmap has already been initialized by GetHCBitMap, and the 
blit rectangle has been initialized to the starting window size by 
the InitBlit procedure. 


Scrolling 

If we got this far, we should be zipping along in our main 
event loop, ready to handle events to our scroll bars. Remember 
from Inside Macintosh that the scroll bars sit on the content 
region of the window, so when we get a mouseDown there, we 
first call FindControl, passing it the location of the mouseDown 
in global coordinates, to find out which control, if any, was hit. 

One possibility is that the user grabs the thumb, in which 
case we call Scroll WithThumb. This routine uses the control 
titles to determine which of the two thumbs, horizontal or 
vertical, was grabbed; then it records the start value of the thumb 
before the thumb is moved. At this point TrackControl is called 
to handle the dragging of the thumb; when the thumb is released, 
the ball is in our court again and we immediately record the 
thumb’s end value. The difference between the start and end 
values (given by the LONGINT amountToScroll) is munged 
through a rearranged version of the Golden Ratio, and the result 
tells us how far to scroll the document. The actual scrolling is 
accomplished by ScrollContents, which first slides the blit rec- 
tangle to the proper location on the offscreen bitmap before 
calling DrawContents to blast the bits to the screen. 

If the user clicks instead on one of the arrows or on a page up/ 
page down region, things get a little more complicated. Let me 
begin by explaining a feature I call “accelerating thumbs.” 

Today’s Macintoshes, of course, are much faster than their 
early predecessors, which is wonderful. Because of this, how- 
ever, it is sometimes very difficult to use scroll bars with any 
precision. Ever try to scroll a list box one line at a time on a Mac 
II? It requires the reflexes of a fighter pilot to scroll less than a 
windowful when you hit the up or down arrows. To solve this 
annoying problem I invented two-speed accelerating thumbs, 
which scroll slowly at first but switch to top speed if you hold the 
mouse down long enough. The page up and page down regions 
work the same way. 

Accelerating thumbs are the reason behind the ScrollRecord 
data structure. The fields of this data structure work in conjunc- 
tion with procedure MyScroll, which is the actionProc 
TrackControl calls repeatedly when the user holds the mouse 
button down in the scroll arrows or page up/page down regions 
(see pp. 1323-324 of Inside Macintosh). Each time the user clicks 
in one of these areas, heldDown is initialized to zero and goFast 
to true before TrackControl is called. TrackControl in turn calls 
MyScroll, and calls it repeatedly until the mouse button is 
released. Each pass through MyScroll scrolls the document one 
notch, the size of the notch depending on whether an arrow or a 
page region is being pressed. It also increments heldDown by one 
and compares it to a preset switching value, which in this case is 
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2. While heldDown is less than 2 we scroll slowly, but when it is 
greater than 2, goFast is set to true and we switch into high gear. 
When the user releases the mouse button, TrackControl is fin- 
ished and the process re-initialized next time a scroll bar is hit. 

MyScrollis definitely the workhorse procedure for the “hard 
part" of scrolling, which is handling the arrows and page regions. 
Icould discuss its workings in great detail here but that would be 
no more informative than reading the source comments. There- 
fore, I refer you to the source comments. Just be aware that 
MyScroll does the math and exception handling for the scroll 
bars, making extensive use of the Golden Ratio, then calls 
ScrollContents to adjust the blit rectangle accordingly. Finally, 
ScrollContents calls DrawContents to blit the stuff to the screen. 

Notice that procedure MyScroll and the routines it calls are 
positioned outside of the Window procedure. This is because 
MyScroll is an actionProc, and the linker can't assign a procPtr 
to it if it is nested. This violates the typical layout of an XCMD 
but is perfectly legal, as long as you don't declare global vari- 
ables. 


Wrapping Up 

If you study this article and the accompanying code listing 
carefully, you will gain a clear understanding of the basics of 
scrolling, offscreen bitmaps, and blitting. If you are a relative 
newcomer to Mac programming, you should congratulate your- 
self for learning one of the most challenging aspects of the Apple 
desktop interface in record time. 

Scrolling has some more knots in it that I didn't even cover. 
For example, what if the user edits the document being scrolled, 
possibly changing its length or width? What if you are scrolling 
acombination of text and graphics? Whatif your document is too 
big to fit into an offscreen bitmap? And how about auto-scrolling 
(when the user drags beyond an edge of the window)? The list 
goes on and on. 

None of these knots are remote possibilities; if your applica- 
tion is at all useful they are inevitable! But untangling them is 
much easier if you understand the basics I've covered in this 
article. Take a look at what other applications are doing. Then 
draw some pictures, remember the Golden Ratio, and everything 
will be all right. 

Happy scrolling! 


(* 
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Window2.p: A HuperCard XCMD in MPW Pascal 2.0.2 
by Joe Zuffoletto 

Version 1.8, 29 June 1988 


Form: Window title, top, left,bottom,right 
Example: window “My Window”,50, 100,300, 400 
Notes: Window puts up а standard document window with 


scroll bars. The window can be dragged, resized, 
zoomed, and closed. 


Command-W is supported for closing the window. 
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Command-spacebar toggles the menubar on and off, 
as in HyperCard. If you try to draw the window s 
title bar off the screen or under the menubar , 
Window will abort with an error message. Error 
messages can be examined by looking at 
HyperCard’s global variable “the result” after 
calling Window. 


Window is MultiFinder friendly and works with 
HyperCard 1.2 or later. It supports multiple 
displays on the Mac II as well. 


Window takes а snapshot of the HyperCard card 
window and displays it like a MacPaint document. 
You can scroll up and down, etc. This is just 
for demonstration and amusement. You must supp ly 
your own code for displaying whatever you want 
to display in the window. 


To compile and link this file using MPW Pascal 2.0.2, select 
the following lines and press ENTER: 


Pascal Window2.p 

link  -o “Hard Disk^:HyperCard: “HyperCard Stacks^:Home à 
-rt ХСМ0-2000 -sn Main=Window 9 
Window2.p.o (MPW)Libraries:Interface.o à 
(MPW)PLibraries:PasLib.o à 
-m ENTRYPOINT 


Use other link files as necessary. 


The above link directives install the XCMD resource into the 
Home stack. You can substitute the name of eny stack you want; 
be Sure to provide the correct pathname. Also, make sure the 
target stack already has a resource fork or it won't work. You 
can create an empty resource fork in a stack 

with ResEdit. 

*) 


($R-) 

($S Window) 
UNIT DummuUnit; 
INTERFACE 


USES 
Memlupes,QuickDraw,OSIntf,ToolIntf,PasLibIntf,HuperXCmd; 


PROCEDURE EntruPoint(paramPtr:XCmdPtr); 
IMPLEMENTATION 
TYPE Str31 = String[31]; 


(Attach to refCon of a window) 
OffScrHandle = ^OffScrRecPtr; 
OffScrRecPtr = “Of fScrRecord; 
Of fScrRecord = RECORD 
gPort: GrafPtr; {offscreen grafPort) 
docWidth: INTEGER; 
docHeight: INTEGER; 
blitRect: Rect; (blit rectangle) 
blitWidth: INTEGER; 
blitHeight: INTEGER; 
dhGraf: LONGINT; 
dvGraf: LONGINT; 
END; 


(Attach to refCon of a scroll bar) 
ScrollHandle = ^ScrollPtr; 
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ScrollPtr = *ScrollRecord; 
ScrollRecord = RECORD 
heldDown: INTEGER; (see Му5сго11) 
goFast: BOOLEAN; 
END; 


PROCEDURE Window(paramPtr :XCndPtr) FORWARD : 


PROCEDURE EntryPoint(paramPtr :XCmdPtr) i 
BEGIN 
WindowCparemPtr); 


д 


FUNCTION MinCint1, int2: INTEGER): INTEGER; 
(Return the smaller of two integers.) 
BEGIN 
IF Cint! <= int2) THEN 
Min := int! 
ELSE 
Min := int2; 
END; (Min) 


PROCEDURE InitBlitCtheWindow:WindowPtr); 

(Initialize the blit rectangle so it is in the upper left 
corner of the offscreen bitmap and so it is the same size 
as the target window onscreen.) 

VAR 
myOf fScrHandle: OffScrHandle; 

BEGIN 
myOf fScrHandle := Of fScrHandle(GetWRef ConC theW indow2); 
MoveHHi CHandleCmyOf f ScrHandle)); 
HLockCHandle(myOf f ScrHandle)); 
WITH myOffScrHandle^^ DO 

N 


BEGI 
dhGraf := 0; 
dvGraf := Ø; 


(Make sure blit rectangle doesn’t hang off edges of 
offscreen bitmap, just in case window is larger.) 


blitWidth := MinCCtheWindow^.portRect.right - 15 - 
theWindow^.portRect . lef t), docWidth); 
blitHeight := MinCCtheWindow^.portRect.bottom - 15 - 
theWindow^.portRect. top), docHeight); 
SetRect(blitRect,gPort^ .portBi ts bounds. left, 
gPort*^ .portBits.bounds top, 


gPort^.portBits.bounds.left * blitWidth, 
gPort^.portBits.bounds.top * blitHeight); 


END; 
HUn lock (Handle(my0f f ScrHandle)); 
END; (InitBlit) 


PROCEDURE InvalContentsCtheWindow:WindowPtr; 
theO1dSize:Rect); 
(Perform *intelligent^ window updating; i.e., if 
the window is grown, invalidate for the update 
event only the part that wasn’t visible before.) 
VAR 
myOf fScrHandle: Of fScrHandle; 
myWindowRect,windowRect: Rect; 
tallRect,wideRect: Rect; 
hWhiteSpace, vWhiteSpace: INTEGER; 
hBlitOffset,vBlitOffset: INTEGER; 
myDocWidth,myDocHeight: INTEGER; 
newDhGraf ,newDvGraf : LONGINT; 
tempDH, tempDV: LONGINT; 
BEGIN 
hBlitOffset := Ø; 
vBlitoffset := 0; 
myWindowRect := theWindow^.portRect; 
nyOf fScrHandle := OffScrHandleCGetWRef ConC theW indow)); 
MoveHH i CHandleCmyOf f ScrHandle)); 
HLockCHaendleCmnyOf f ScrHandle)); 
WITH nyOffScrHandle^^ DO 
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BEGIN 
tempDH := dhGraf ; 
tempDV := dvGraf ; 
myDocWidth := docWidth; 
myDocHeight := docHeight; 
END; 


(If we have scrolled to the bottom and/or right edges 

of the document and then grow the window, the document 
will “follow” the window so we don’t just expose a lot 

of white space. The same thing will happen if we zoom the 
window to a larger size. In either case, we need to 
invalidate the entire content region.) 


(Is any white space being exposed in horizontal 
direction?) 


hWhiteSpace := (myWindowRect.right - 
myWindowRect. left - 15) - 
CmyDocWidth - tempDH); 


IF ChWhiteSpace > 0) THEN 
BEGIN 
(If so, how much?) 


newDhGraf := tempDH - hWhiteSpace; 


(Move the document that distance, but not beyond the 
point where its left edge is flush with the left edge 
of the window.) 


IF newDhGraf < 0 THEN 
newDhGraf := 0; 


(Adjust blit rectangle accordingly.) 


hBlitOffset := INTEGERCtempDH - newDhGraf ); 
tempDH := newDhGraf; 
END; (IF hWhiteSpace) 
(Repeat for vertical direction.) 
vWhiteSpace := CmyWindowRect .bottom - 
myWindowRect.top - 15) - 
CmyDocHeight - tempDV); 
IF CvWhiteSpace > 0) THEN 
BEGIN 
newDvGraf := tempDV - vWhiteSpace; 
IF newDvGraf « 0 THEN 
newDvGraf :- 0; 
vBlitOffset := INTEGERCtempDV - newDvGraf ); 
tempDV := newDv6raf; 
END; (IF vWhiteSpace) 


(Save what we've learned to the data structure.) 


WITH myOffScrHandle^^ DO 
BEGIN 
dnGraf := tempDH; 
dvGraf := tempDV; 
blitWidth := MinCCmyWindowRect .right - myWindowRect.left - 
15), 
CmyDocWidth - dhGraf)); 
blitHeight := Min(CmyWindowRect bottom - тун indowRect. top 
- 15), 
(myDocHeight - dvGraf )); 
SetRect(blitRect,blitRect.left - hBlitOffset, 
blitRect.top - vBlitOffset, 
blitRect.left + blitWidth - hBlitOffset, 
blitRect.top + blitHeight - vBlitOffset); 
blitWidth := blitRect.right - blitRect. left; 
blitHeight := blitRect.bottom - blitRect.top; 


END; 
HUnlockCHandleCmyOf f ScrHandle2); 
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(If the document has followed the window, invalidate entire 
content region.) 


IF CC(hBlitOffset © 0) OR CvBlitOffset € 022 THEN 
BEGIN 
EraseRect(CtheWindow^.portRect); 
InvalRectCtheWindow^ .portRect); 
END 
ELSE 


(Otherwise invalidate only the new white space.) 


BEGIN 
SetRectCtallRect, theO1dSize.right, 
theWindow^ .portRect . top, 
theWindow* .portRect.right, 
theWindow* .portRect.bottom); 
SetRect(wideRect, theWindow^ .portRect. left, 
theO1dS ize .bottom, 
theO0ldSize.right, 
theWindow^.portRect .bottom?; 
EraseRect(CtallRect?; 
EraseRect(wideRect); 
InvalRectCtallRect?; 
InvalRect(wideRect); 
END; (IF hBlitOffset) 
END; (InvalContents) 


PROCEDURE DrawContents(theWindow:WindowP tr); 
„з contents of updated blit rectangle to screen.) 
myWindowRect,windowRect: Rect; 
myOf f ScrHandle: Of fScrHandle; 
BEGIN 
myOf fScrHandle := OffScrHaendleCGetWRef ConCtheWindow)); 
myWindowRect := theWindow^.portRect ; 
MoveHHi CHandle(CmyOf fScrHandle)); 
HLock (Hand leCmy0f fScrHandle)); 
SetRect(windowRect, myWindowRect. left, 
myWindowRect. top, 
myWindowRect. left + 
myOf fScrHandle** .blitWidth, 
myWindowRect.top + 
myOf fScrHandle** .blitHeight); 
ClipRect(windowRect); 
CopyBits(myOf fScrHandle**.gPort*.portBits, theWindow^ .portBits, 
myOf f ScrHandle^^.blitRect,windowRect, srcCopy, NIL); 
HUnlockCHandle(CmyOf fScrHandle)); 
END; (DrewContents) 


PROCEDURE ScrollContentsCtheWindow:WindowPtr; 
dh, dv: INTEGER); 
VAR 


myOf f ScrHendle: OffScrHandle; 
leftSpace, topSpace: INTEGER; 
rightSpace,bottomSpace: INTEGER; 

BEGIN 
myOf fScrHandle := Of fScrHandle(GetWRefCon( theW indow)); 
MoveHH i CHandleCmyOf f ScrHandle2); 
HLockCHandleCmgOf f ScrHandle)); 


(Calculate space between edges of blitRect and edges 
of the bitmap.) 


WITH myOffScrHandle^^ DO 
BEGIN | 
leftSpace := gPort^.portBits.bounds.left - blitRect. left; 
topSpace := gPort^.portBits.bounds.top - blitRect. (ор; 
rightSpace := gPort^.portBits.bounds.right - 
blitRect.right; 
bottomSpace := gPort^.portBits.bounds.bottom - 
blitRect.bottom; 
END; 
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tempDH := dhGraf; 


(Then move blitRect, but not past the edge of the bitmap.) tempDV := dvGraf; 
myDocWidth := docWidth; 
IF (dv = 0) THEN myDocHeight := docHeight; 
IF (dh > 8) THEN (moving to the right) END; 
IF (rightSpace > dh) THEN HUnlockCHandle(mgOf f ScrHand1e )); 
Of fsetRect (myOf fScrHandle^^.b1litRect, dh, dv) 
ELSE (Initialize more variables for our formulas.) 
BEGIN 
dh := rightSpace; visHeight := theWindow^.portRect.bottom - 15 - 
Of fsetRectCmyOf fScrHandle^^.blitRect, dh, dv); theWindow^ .portRect . top; 
END visWidth := theWindow^.portRect.right - 15 - 
ELSE IF CleftSpace > dh) THEN (moving to the left) theWindow^.portRect.left; 
BEGIN StartValue := GetCtlValueCtheContro1); 
dh := lef tSpace; GetCTitleCtheControl, direction); 
Of fsetRect(myOf fScrHandle**.b1itRect, dh, dv); myScrollHandle :- Scrol lHandle(GetCRefCon( theContro1)); 
END MoveHHi(Handle(muScrollHandle)); 
ELSE HLock(Handle(muScrollHandle)); 
OffsetRect(myOf fScrHendle^^.blitRect, dh, dv) 
ELSE IF (dv > Ø) THEN (moving down) (Implementation of two-speed, accelerating scroll bars.) 
IF CbottomSpace > dv) THEN 
Of fsetRect (myOf fScrHandle**.b1itRect,dh, dv) WITH myScrollHandle^^ DO 
ELSE BEGIN 
BEGIN heldDown := heldDown + 1; 
dv := bottomSpace; IF CheldDown > 2) THEN 
OffsetRect(mgOf f ScrHandle^^.b1itRect, dh, dv); goFast := TRUE; 
END END; (WITH) 
ELSE IF (topSpace > dv) THEN (moving up) 
BEGIN CASE partCode OF 
dv := topSpace; inUpButton: 
OffsetRect(myOf fScrHandle^^.blitRect, dh, dv); BEGIN 
END (Don^t scroll up if already at top!) 
ELSE IF (startValue > 0) THEN 
Of fsetRect(myOf fScrHandle^^.blitRect, dh, dv); BEGIN 
IF (direction = 'MyVert^) THEN 
(Save actual distances moved to data structure.) BEGIN 
IF (visHeight >= myDocHeight) THEN 
WITH myOffScrHandle^* DO BEGIN 
BEGIN setCtlValueCtheControl,2); 
dh6raf :- dhGraf + dh; ScrollContents(theWindow,0,-tempDV); 
dvGraf := dvGraf + dv; END 
END; ELSE 
HUnlockCHandle(myOf f ScrHandle)); BEGIN 
(Scroll up five pixels) 
(Shoot new contents of blit rectangle to screen.) dv := tempDV - 5; 
DrawContents(theWindow); (Set new thumb value using Golden Ratio.) 


END; (ScrollContents) 
myCtlValue := LONGINTCCdv ж myDocHeight) DIV 


PROCEDURE MyScrollCtheContro! :ControlHandle; CmyDocHeight - visHeight)); 
partCode: INTEGER); ClipRect(theWindow*.portRect); 
VAR setCt1Value( theControl, INTEGERCmyCt1Value)): 
nyOf fScrHandle: OffScrHandle; 
myScrollHandle: ScrollHandle; (Update blit rectangle, blast document to screen.) 
dh,dv: LONGINT; 
windowFull: LONGINT; ScrollContentsCtheWindow,8, -5); 
myCtlValue: LONGINT; END; (IF visHeight...ELSE) 
visHeight,visWidth: LONGINT; END 
dontCare: LONGINT; ELSE 
tempDH, tempDV: LONGINT; BEGIN 
startValue: INTEGER; (Repeat for horizontal direction.) 
myDocWidth,myDocHeight: INTEGER; IF (visWidth >= myDocWidth) THEN 
direction: Str255; BEGIN 
theWindow: WindowPtr; setCtliValueCtheContro!,0); 
BEGIN ScrollContentsCtheWindow, -tempDH, 2); 
theWindow := theControl^^.contrlOwner; END 
myOf fScrHandle := Of fScrHandle(GetWRef ConCtheWindow2); ELSE 
MoveHH i CHandleCmyOf f ScrHand1e)); BEGIN 
HLockCHandleCmyOf f ScrHandle)); dh := tempDH - 5; 
myCtiValue :- LONGINTCCdh х myDocWidth) DIV 
(Make local copies of data structure items.) (myDocWidth - visWidth)); 
ClipRectCtheWindow^ .portRect); 
WITH myOffScrHandle** DO setCtlValueCtheContro!, INTEGERCmyCt1Value)); 
BEGIN ScrollContentsCtheWindow, -5,0); 
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END; (IF visWidth...ELSE) 
END; (IF direction...ELSE) 
END; (IF startValue) 
IF (myScrollHandle^^.goFest = FALSE) THEN 
DelayC12, dontCare); 
END; (inUpButton) 


(Pattern is identical for down button, page up, 
and page down regions.) 


inDownButton: 
BEGIN 
IF (direction = ‘MyVert’) THEN 
BEGIN 
IF (staertValue < myDocHeight) THEN 
BEGIN 
dv := tempDV + 5; 
myCtlValue := LONGINTCCdv * myDocHeight) DIV 
(nyDocHeight - visHeight2); 
ClipRectCtheWindow^ .portRect); 
setCtlValueCtheContro1, INTEGERCmyCt1Value)); 
ScrollContentsCtheWindow,2,52; 
END; (IF staertValue) 
END 
ELSE 
BEGIN 
IF (startValue < myDocWidth) THEN 
BEGIN 
dh := tempDH + 5; 
myCtlValue := LONGINTCCdh х myDocWidth) DIV 
(muDocWidth - visWidth)); 
ClipRectCtheWindow^ .portRect); 
setCtlValueCtheControl, INTEGERCmyCt1Value)); 
ScrollContentsCtheWindow,5,0); 
END; (IF startValue) 
END; (IF direction... ELSE) 
IF (myScrollHandle^^.goFast = FALSE) THEN 
Delau(10,dontCare); 
END; (inDownButton) 


inPageUp: 
BEGIN 
IF (startValue > 0) THEN 
BEGIN 
IF (direction = ‘MyVert’) THEN 
BEGIN 
IF (visHeight >= myDocHeight) THEN 
BEGIN 
setCt1Value( theControl, ð); 
ScrollContentsCtheWindow, 0, -tempDV); 
END 
ELSE 
BEGIN 
windowFull := visHeight - 5; 
dv := tempDV - windowFull; 
IF (dv < 0) THEN 
dv := 0; 
muCtlValue := LONGINTCCdv * muDocHeight) DIV 
(muDocHeight - 
visHeight)); 
ClipRect(theWindow .portRect); 
setCtlValue(theControl,INTEGER(muCtlValue)); 
ScrollContents(theWindow,0,-windowFul1); 
END; (IF visHeight...ELSE) 
END (IF direction) 
ELSE 
BEGIN 
IF (visWidth >= myDocWidth) THEN 
BEGIN 
setCt1ValueCtheContro1,0); 
ScrollContentsCtheWindow,-tempDH,0); 
END 
ELSE 
BEGIN 
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windowFull := visWidth - 5; 
dh := tempDH - windowFull; 
IF (dh < Ø) THEN 
dh := 0; 
myCtlValue := LONGINTCCdh * myDocWidth) DIV 
(myDocWidth - visWidth)); 
ClipRectCtheWindow^ .portRect); 
setCtlValueCtheControl, INTEGERCnyCt1Value2); 
ScrollContentsCtheWindow,-windowFu11,92; 
END; (IF visWidth...ELSE) 
END; (IF direction... ELSE) 
IF (myScrollHendle^^.goFast = FALSE) THEN 
Delay( 18, dontCare); 
END; (IF startValue) 
END; (inPageUp) 


inPageDown: 
BEGIN 
IF (direction = ‘MyVert’) THEN 
BEGIN 
IF (startValue < myDocHeight) THEN 
BEGIN 
windowFull := visHeight - 5; 
dv := tempDV + windowFull; 
myCtlValue := LONGINTCCdv * myDocHeight) DIV 
CmyDocHeight - visHeight)); 
ClipRectCtheWindow^ .portRect); 
setCt]Value( theControl, INTEGERCmyCt1Value)); 
ScrollContents( theW indow, 0, windowFul 1); 
END; (IF startValue) 
END (IF direction) 
ELSE 
BEGIN 
IF (startValue < myDocWidth) THEN 
BEGIN 
windowFull := visWidth - 5; 
dh := tempDH + windowFull; 
myCtlValue := LONGINTCCdh * myDocWidth) DIV 
(myDocWidth - visWidth)); 
ClipRectCtheWindow^ .portRect); 
setCt]Value( theControl, INTEGERCmyCt1Value)); 
ScrollContentsCtheWindow,windowFu11,22; 
END; (IF startValue) 
END; (IF direction... ELSE) 
IF (myScrollHandle^^.goFast = FALSE) THEN 
Delay( 10, dontCare?; 
END; (inPageDown) 


END; (CASE partCode) 

HUnlockCHandle(myScrollHandle2); 

ClipRectCtheWindow^ .portRect); 

(so TrackControl can unhilite arrows when mouse is released) 
END; (MuScroll) 


PROCEDURE Window(paramPtr :XCmdPtr ); 


CONST 
minParamCount = 5; 
smallestHeight = 100; 
smallestWidth = 100; 
_WaitNextEvent = $4860; 
-Unimplemented = $A89F; 
active = 0; 
inactive = 255; 
MouseMovedEvt = ФҒА; 
SuspendResumeEvt = $01; 
SuspendEventMask = $1; 
ConvertScrapMask = §2; 
browseToo! = 6069; 
HCWidth - 512; 
HCHe ight = 342: 
padding = 16; 

VAR 
toolVis, patVis: BOOLEAN; 
msgVis, fatVis: BOOLEAN; 
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hasWaitNextEvent: BOOLEAN; 
inBackGround,smallScreen: BOOLEAN; 
DoneFlag,HaveEvent: BOOLEAN; 
wlop,wleft,wBottom,wRight: INTEGER; 
partCode, controlCode: INTEGER; 
largestHeight, largestWidth: INTEGER; 
dummy, charCode : INTEGER; 
screenWidth,screenHeight: INTEGER; 
myDocWidth, myDocHe ight: INTEGER; 
eventPoint: Point; 
wRect,screenRect,dragRect: Rect; 
winSizeLimits: Rect; 
oldSize: Rect; 
newSize,dontCare: LONGINT; 
envError : OSErr; 
cursorRgn: RgnHandle; 
hScrol!, vScro11: ControlHandle; 
whichControl: ControlHandle; 
myWindow, whichWindow: WindowPtr; 
fatBitsWindow: WindowP tr ; 
HCrefresh: Str31; 
wT,wL,wB,wR,wTitle: Str255; 
toolStr,patStr,msgStr: 517255; 
widthStr,heightStr: Str255; 
muBits: BitMap; 
theEnv: SusEnvRec; 
muEvent: EventRecord; 
wRecord: WindowRecord; 
HCPort: GrafPtr; 
theOf fScrHandle: Of fScrHandle; 
theScrollHandl]e: ScrollHandle; 
myOf f Scr : OffScrRecord; 
muScrollRecord: ScrollRecord; 


FUNCTION TrapAvailable(tNumber: INTEGER; tTupe: 
TrapTupe):BOOLEAN; 
(Check to see if a given trap is implemented.) 


BEGIN 
TrapAvailable 


:= NGetTrapAddress(tNumber, tTupe) © 


GetTrapAddress(_Unimplemented); 


END; (TrapAvailable) 


FUNCTION CreateHScrollBar(theWindow:WindowPtr; 


theValue, theMin, theMax: INTEGER; 


theRefCon :LONGINT):ControlHandle; 


(Allocate and draw a horizontal scroll bar in theWindow. 
21 а controlHandle to the scroll bar.) 
AR 
myWindowRect,hScrRect: 
BEGIN 
Se tPor tC theWindow); 
myWindowRect := theWindow^.portRect; 
SetRect(hScrRect, myWindowRect. left -1, 
myWindowRect.bottom - 15, 
myWindowRect.right - 14, 
myWindowRect.bottom + 1); 
CreateHScrollBar := NewControlCtheWindow,hScrRect, 
"MyHor iz’, TRUE, 
theValue, theMin, theMax, 
ѕсго11ВагРгос, theRef Con) 


Rect; 


END; (CreateHScrollBer) 


FUNCTION CreateVScrollBarCtheWindow:WindowPtr; 
theValue, theMin, theMax: INTEGER; 
theRefCon:LONGINT2:ControlHandle 

{Allocate and draw a vertical scroll bar in theWindow. 

Return a controlHandle to the scroll bar.) 


VAR 
myWindowRect,vScrRect: Rect; 
BEGIN 
SetPort(theWindow); 
myWindowRect := theWindow^.portRect; 


SetRect(vScrRect, myWindowRect.right -15, 
myWindowRect.top - 1, 
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myWindowRect.right + 1, 
myWindowRect.bottom - 14); 
CreateVScrollBar := NewControl(theWindow, vScrRect, 
"MyVert^, TRUE, 
theValue, theM in, theMax, 


ѕсго11ВагРгос, theRef Con); 


END; (CreateVScrollBar) 


PROCEDURE InvalScrollCtheWindow:WindowPtr); 
(Accumulate the rectangles occupied by theWindow’s 
horizontal and vertical scroll bars into the update 


region.) 
VAR 
theRect,tallRect,wideRect: Rect; 
BEGIN 
SetPortCtheWindow); 
theRect := theWindow^.portRect; 
ClipRectCtheRect); 


(Accumulate tallRect, which is occupied by the vertical 
scroll bar ) 


SetRectCtallRect, theRect .right- 15, 
theRect . top, 
theRect .right, 
theRect .bottom); 

EraseRectCtallRect); 

InvalRectCtallRect); 


(Accumulate wideRect, which is occupied by the 
horizontal scroll bar ) 


SetRect(wideRect, theRect . lef t, 
theRect .bottom- 15, 
theRect .r ight, 
theRect .bottom); 

EreseRect(wideRect); 

InvalRect(wideRect); 

END; (InvalScro11) 


PROCEDURE Deact ivate( theW indow: WindowPtr ); 

(Deactivate the scroll bars in theWindow in accordance 
with the human interface guidelines. This means we 
must erase everything enclosed by the contro] rec- 


tangles. } 

VAR 
theContro! : ControlHandle; 
theControlRect: Rect; 

BEGIN 


(I always title my scroll bars ‘MyVert’ and 'MyHoriz' 
so I can easily find them by walking a window’s 
control list.) 
theControl := WindowPeek( theWindow)*.controlList; 
WHILE (theControl © NIL) DO 
BEGIN 
IF CtheControl**.contriTitle = ‘MyVert’) OR 
(theControl^^.contrlTitle = ‘MyHoriz’) THEN 
BEGIN 
theControlRect := theControl^^.contrlRect; 
InsetRectCtheControlRect, 1, 1); 
EraseRectCtheControlRect); 
END; (IF) 
theContro] 
END; (WHILE) 
END; (Deactivate) 


:= theControl**.nextControl; 


PROCEDURE HiliteScrollBarsCtheWindow:WindowPtr); 
VAR 

myWindowRect: Rect; 

visWidth,visHeight: INTEGER; 

myDocWidth, myDocHeight: INTEGER; 

muCtlValue: INTEGER; 

tempDH, tempDV: LONGINT; 

myOf fScrHandle: OffScrHandle; 
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BEGIN 
myOffScrHandle := OffScrHandleCGetWRef ConCtheWindow2); 
MoveHH i CHandleCmyOf f ScrHandle?); 
HLockCHandleCmyOf f ScrHandle)2); 


(Make local copies of data structure items.) 


WITH myOffScrHandle^^ 00 
BEGIN 
tempDH := dhGraf ; 
tempDV := dvGraf ; 
myDocWidth := docWidth; 
myDocHeight := docHeight; 
END; 


HUnlock(Handl1e(mu0ffScrHandle)); 

myWindowRect := theWindow .portRect; 

visHeight := muWindowRect.bottom - 15 - muWindowRect.top; 
visWidth := muWindowRect.right - 15 - muWindowRect.left; 
SetPort(theWindow); 

ClipRect(muWindowRect); 


(Check to see if window is taller than contents. If 
so, unhilite vertical scroll bar. Otherwise, use 
Golden Ratio to draw vertical scroll bar with thumb 
in right position.) 


IF ((visHeight >= muDocHeight) AND CtempDV = 8)) THEN 
HiliteControl(vScro11, INTEGERC inactive )) 
ELSE 
BEGIN 
HiliteControlCvScrol], INTEGERCactive)); 
IF (visHeight >= myDocHeight) THEN 
SetCt1ValueCvScrol1,myDocHe ight) 
ELSE 
BEGIN 
muCtlValue := LONGINTCCtempDV < myDocHeight) DIV 
(myDocHeight - visHeight)); 
ClipRectCtheWindow^ .portRect); 
setCtlValueCvScrol1, INTEGERCmyCt1Value)); 
Ë END; (IF visHeight...ELSE) 
ND; 


(Repeat for horizontal scroll bar.) 


IF ((visWidth >= myDocWidth) AND (tempDH = 0))THEN 
HiliteControl(hScroll,INTEGER(inactive)) 
ELSE 
BEGIN 
HiliteControl(hScroll,INTEGER(active)); 
IF (visWidth >= myDocWidth) THEN 
SetCtlValue(hScroll,muDocWidth) 
ELSE 
BEGIN 
muCtlValue := LONGINT((tempDH * myDocWidth) DIV 
(muDocWidth - visWidth)); 
ClipRect(theWindow .portRect); 
setCtlValueChScrol], INTEGERCmyCt1Value)); 
END; (IF visWidth...ELSE) 
END; (IF visWidth...ELSE) 


END; (HiliteScrollBars) 


PROCEDURE MoveScrol1Bars(theWindow:WindowPtr); 

(Call this procedure after theWindow has changed size. 
MoveScrollBars erases theWindow’s scroll bars, resizes 
them, and redraws them.) 


VAR 
nyWindowRect: Rect; 
vScrRect,hScrRect: Rect; 
BEGIN 


myWindowRect := theWindow^.portRect; 
SetRectChScrRect,myWindowRect.left - 1, 
myWindowRect.bottom - 15, 
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myWindowRect.right - 14, 
myWindowRect.bottom + 1); 
SetRect(vScrRect,muWindowRect.right - 15, 
myWindowRect.top - 1, 
myWindowRect.right + 1, 
myWindowRect.bottom - 14); 
SetPortCtheWindow); 
ClipRectC(nyW indowRect ); 


(Hide and resize the scroll bars to fit the new window 
size.) 


HideControlChScro112; 
HideControlCvScro11); 


MoveControlChScro11,hScrRect . lef t, hScrRect . (ор); 
SizeControlChScroll,ChScrRect.right - hScrRect. left), 
(hScrRect.bottom - hScrRect.top)); 


MoveControl(CvScroll,vScrRect . lef t, vScrRect . top); 

SizeControl(vScroll,CvScrRect.right - vScrRect. left), 
(vScrRect.bottom - vScrRect.top)); 

HiliteScrollBarsCtheWindow); 

ShowControlChScro112; 

ShowControlCvScro112; 


END; (MoveScrollBars) 
PROCEDURE ScrollWithThumbCtheContro! : ControlHandle; 
VAR 


theEventPoint Point); 


theWindow: WindowPtr; 

myOf fScrHandle: Of fScrHandle; 

visWidth, visHeight: INTEGER; 

myDocWidth, myDocHeight: INTEGER; 

startValue,endValue: INTEGER; 

dummy: INTEGER; 

amountToScroll: LONGINT; 

tempDH, tempDV: LONGINT; 

direction: Str255; 

BEGIN 
theWindow := theControl^^.contrlOwner; 
myOffScrHandle := OffScrHandleCGetWRef ConCtheWindow)); 
MoveHHiCHandleCmyOf f ScrHandle2); 
HLockCHandleCmyOf fScrHandle)); 


(Make local copies of the data structure items.) 


WITH nyOffScrHandle^^ DO 
BEGIN 
tempDH := dh6Graf; 
tempDV := dvGraf; 
myDocWidth := docWidth; 
myDocHeight := docHeight; 
END; 
HUnlockCHandleCmyOf f ScrHandle)); 
GetCTitleCtheControl,direction); 
visHeight := theWindow^.portRect.bottom - 
theWindow^.portRect.top - 15; 
visWidth :- theWindow^.portRect.right - 
theWindow^.portRect.left - 15; 


(Record where thumb is before it is moved.) 
startValue := GetCtlValueCtheContro1); 

(Move it.) 

dummy := TrackControl(theControl, theEventPoint , NIL); 
(Record where thumb is released.) 

endValue := GetCtlValueCtheControl); 


(Record the distance thumb was moved.) 
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emountToScroll := LONGINTCendValue - startValue); 
IF (direction = ‘MyVert’) THEN 
BEGIN (moved vertical scroll bar) 
IF CendValue = 0) THEN (moved thumb to top) 
ScrollContentsCtheW indow, 8,-tempDV) 
ELSE IF CendValue = myDocHe ight) THEN 
(moved thumb to bottom) 
ScrollContentsCtheWindow,2,myDocHeight - tempDV) 
ELSE 
BEGIN 
(moved thumb somewhere in middle - use 
Golden Ratio to translate thumb movement 
into document movement.) 
emountToScroll := LONGINTCCamountToScroll * 
(mgDocHeight - 
visHeight)) DIV 
myDocHe ight); 
IF CABSCamountToScrol1) < 1) THEN 
(didn't move thumb far enough to scroll - 
snap it back to starting position.) 
SetCtlValueCtheControl,startValue) 
ELSE 
9crollContentsCtheWindow,8, 
INTEGERCamountToScro11)); 
END; 


END 

ELSE (moved horizontal scroll bar) 

BEGIN 

IF CendValue = 0) THEN 
ScrollContentsCtheWindow, -tempDH, 0) 

ELSE IF CendValue = myDocWidth) THEN 
ScrollContentsCtheWindow,myDocWidth - tempDH,2) 


ELSE 
BEGIN 
emountToScroll := LONGINTCCamountToScro]l] * 
(myDocWidth - 
visWidth)) DIV 
myDocWidth); 


IF CABSCamountToScrol1) < 1) THEN 
SetCtlValueCtheControl,startValue) 
ELSE 
ScrollContentsCtheWindow, 
INTEGERCamountToScro11),8); 
END; 


END; 
END; (ScrollWithThumb) 


FUNCTION WhichDevice( thePoint :Point):GDHandle; 

(For machines that support color QuickDraw and 

multiple screens, WhichDevice figures out which screen 
thePoint is on and returns a GDHandle to that screen. 
thePoint might be where the mouse was clicked, for 


example. Thanks to Greg Marriott for this code.) 
VAR 


aDevice: GDHandle; 

foundOne: BOOLEAN; 
BEGIN 

aDevice := GetDeviceList; 


foundOne := FALSE; 


(Walk the device list until thePoint is contained 
in some device's screen rectangle.) 


WHILE (aDevice <> NIL) AND NOT foundOne DO 
BEGIN 
IF PtInRectCthePoint,aDevice^^ 
BEGIN 
WhichDevice := aDevice; 
foundOne := TRUE; 
END; 
eDevice := aDevice~* 
END; 


.gdRect) THEN 


.gdNextGD; 
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END; (WhichDevice) 


FUNCTION MenuBarHeight: INTEGER; 

(Returns the height of the menubar in pixels, as read 
from the low memory global mBarHeight.) 

CONST 
mBarHeight = $BAA; 

VAR 


menuBarHeightPtr: “INTEGER; 
BEGIN 
menuBarHeightPtr := Pointer (mBarHe ight); 


MenuBarHeight := menuBarHeightPtr^; 
END; (MenuBarHe ight) 


FUNCTION OnAScreenCtheRect :Rect): BOOLEAN; 

(OnAScreen returns FALSE if all of a window’s title 
bar is off the screen or if any part of it is under 
the menubar. The portRect of the window to be checked 
should be passed in theRect.) 


CONST 
titleBarHeight = 18; 
VAR 
deskRgn: RgnHandle; 
topLeft,topRight: Point; 
BEGIN 
deskRgn := GetGrayRgn; 


topLeft.v := theRect.top - titleBarHeight; 
topLeft.h := theRect.left + titleBarHeight; 
topRight.v := topLeft.v; 
topRight.h := theRect. right - titleBarHeight; 
IF (CPtInRgnC topLef t, deskRgn)) OR 
(PtInRgn( topRight, deskRgn))) THEN 
OnAScreen := TRUE 
ELSE 
OnAScreen := FALSE; 
END; (OnAScreen) 


PROCEDURE ZoomIt(theWindow:WindowPtr;partCode: INTEGER; 
clickedWhere Point); 

(ZoonIt supports more elegant window zooming on multiple 
Screen systems. theWindow will zoom to fill whatever 
Screen the zoom box was on when it was clicked. The 
window state toggles between original size and zoomed 
Size, as usual. Thanks to Greg Marriott for this code.) 

CONST 

titleBarHeight = 18; 


TYPE 
WStatePtr = “WStateData; 
WStateHendle =  ^WStatePtr; 
VAR 
oldRect,newRect: Rect; 
maxHeight: INTEGER; 
BEGIN 
oldRect := theWindow^.portRect; 
IF theEnv.hasColorQD THEN 
BEGIN 
newRect := WhichDevice(clickedWhere)**.gdRect; 


IF WhichDevice(clickedWhere) = GetMainDevice THEN 
newRect.top :- newRect.top + MenuBarHeight; 
END 
newRect := GetGrayRgn^^.rgnBBox; 
newRect. left := newRect.left + 2; 
newRect.top := newRect.top + titleBarHeight + 2; 
newRect right := newRect.right - 3; 
newRect bottom := newRect.bottom - 3; 
IF NOT EqualRect(oldRect, newRect) THEN 
WITH WindowPeek ће indow)^ 00 
WStateHandleCdataHandle)**.stdState := newRect; 
SetPortCtheWindow); 
EreseRect(whichWindow^ .portRect); 
InvalRect(whichWindow^ .portRect); 
ZoomW indow( theW indow, par tcode, FALSE); 
END; (ZoonIt) 
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($I XCmdGlue.inc) 


PROCEDURE Fail(errStr:Str255); 

(Fail returns errStr to HyperCard and exits the XCMD. 
errStr can then be checked by inspecting HyperCard’s 
global variable “the result.” See “XCMD’s for Hyper- 
Сага” by Gary Bond (MIS Press, 1988) for more details. 


@ 1988 by Gary Bond 
All rights reserved. 
You may use this code for NON-COMMERCIAL purposes. } 
BEGIN 
paramPtr^.returnValue :- PasToZeroCerrStr ); 
SysBeep( 1); 
EXITCWindow); 
END; (Fail) 


PROCEDURE CheckParamCount; 

(CheckParamCount sees if the number of parameters 
passed to the XCMD matches the number expected. If 
not, we exit from the XCMD with an error message. 
See “XCMD’s for HyperCard” by Gary Bond (MIS Press, 
1988) for more details. 


@ 1988 by Gary Bond 
All rights reserved. 
a may use this code for NON-COMMERCIAL purposes. } 
R 
numParams: INTEGER; 
BEGIN 
numParams := paramPtr^.paremCount; 
IFCnumParams ‹› minParamCount) THEN 
FailC'Form: HyperWindow “Window 
Title’, top, left, bottom, right’); 
END; (CheckParamCount) 


FUNCTION GetHCVersion: Str255; 
(Return a string containing the version of HyperCard 
being used; e.g., 71.27”) 
BEGIN 
ZeroToPas(EvalExpr( ‘the version’ )*,GetHCVersion); 
END; (GCetHCVersion) 


PROCEDURE HideWindoids; 
(Get and save the visible state of the tool, pattern, 
message and fatbits windoids; then hide them if they 
are showing.) 
VAR 
toolH,patH,msgH,fatH: Handle; 
PROCEDURE HideFatBits; 
(HyperCard does not have a built-in command for hiding 
end showing the fatbits windoid, so we have to do it 
ourselves. HideFatBits walks the window list until it 
finds a window with title “FatBits,” then hides it if 
the visible field of its WindowRecord is true. 
HideFatBits also saves the WindowPtr to the fatbits 
windoid so we can use it later (е.0., to show the 
windoid again).} 


CONST 

windowList = $906; (Low memory global location.) 
VAR 

theWindow: WindowPeek; 

theWindowPtr:  ^WindowPtr; 
BEGIN 


theWindowPtr := PointerCwindowList); 
theWindow := WindowPeek( theWindowP tr 2; 
fatVis := FALSE; 
WHILE CtheWindow © NIL) DO 
BEGIN 
IF (theWindow*.titleHandle** = ‘FatBits’) THEN 
BEGIN 
fatBitsWindow := WindowPtr( theW indow); 
IF CtheWindow* visible = TRUE) THEN 
BEGIN 
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fatVis := TRUE; 
HideWindowCfatBitsWindow); 
theWindow := NIL; 
END; 
END; 
IF (thewindow © NIL) THEN 
theWindow := WindowPeek(theWindow) .nextWindow; 
END; (WHILE) 
END; (HideFatBits) 


BEGIN (HideWindoids) 
(Get visible state of windoids.) 


toolH := EvalExpr( ‘visible of tool window’); 
ZeroToPas(toolH*, toolStr); 
DisposHandleCtoolH); 

toolVis := StrToBoolCtoolStr); 


patH := EvalExpr(C'visible of pattern window’); 
ZeroToPas(patH^ ,patStr 2; 

DisposHandle(patH); 

patVis := StrToBool(patStr); 


msgH := EvalExpr(‘visible of message window’); 
ZeroToPas(msgH^ , msgstr); 

DisposHandle(msgH?; 

msgVis := StrToBool(msgStr); 


(Hide the ones that are showing.) 
HideFatBits; 


IF toolVis THEN 
SendHCMessage( ‘hide tool window’); 
IF patVis THEN 
SendHCMessage( ‘hide pattern window’); 
IF msgVis THEN 
SendHCMessage( ‘hide message window’); 
END; (HideWindoids) 


PROCEDURE ShowWindoids; 
(This routine assumes HideWindoids has been called 
before. ShowWindoids restores the visible state of 
the windoids to that saved by HideWindoids.) 
BEGIN 
IF toolVis THEN 
SendHCMessage( ‘show tool window’); 
IF patVis THEN 
SendHCMessage( ‘show pattern window’); 
IF msgVis THEN 
SendHCMessage( ‘show message window’); 


(As in HideWindoids, we must take care of the FatBits 
windoid ourselves.) 


IF fatVis THEN 

BEGIN 
ShowWindowCfatBitsWindow); 
SelectWindowCfatBitsWindow); 


END; 
END; (ShowWindoids) 


PROCEDURE ToggleMenuBar; 
(Set the visible of the menubar to not the visible of 
the menubar.) 
BEGIN 
IF MenuBarHeight = Ø THEN 
SendHCMessage( ‘show menubar’) 
ELSE 
SendHCMessage( hide menubar’); 
END; (ToggleMenuBar) 


PROCEDURE GetHCBi tMap; 
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VAR 


muDocHeight,muDocWidth: INTEGER; 
HCRect,muHCRect: Rect; 
dummyGrafPtr: GrafPtr; 
HCBits: BitMap; 

BEGIN 


MoveHHiCHandleCtheOf fScrHandle)); 
HLockCHandleCtheOf fScrHandle)); 
WITH theOffScrHandle^^ DO 


BEGIN 
myDocWidth := docWidth; 
myDocHeight := docHeight; 
END; 


myBits.rowBytes := (((muDocWidth - 1) DIV 16) + 1) * 2; 
myBits.baseAddr :- NewPtr(myBits.rowBytes * myDocHeight); 
IF (myBits.baseAddr = NIL) THEN 

FailC'Could not allocate bitmap. ^); 
HCRect := HCPort^.portRect; 
HCBits := HCPort^.portBits; 
SetRect(myBits.bounds,9, Ø, 528, 358); 


dummyGrafPtr := GrafPtr(NewPtr(sizeOf(GrafPort))); 
IF (dummuGrafPtr = NIL) THEN 
BEGIN 
DisposPtr(muBits.baseAddr); 
FailC'Could not allocate offscreen grafPort.’); 

END; 
theOffScrHandle**.gPort := dummyGrafPtr ; 
OpenPor t( theOf f ScrHandle** .gPort); 
SetOrigin(0,0); 
SetPortBits(muBits); 
MovePortTo(0,0); 
PortSize(muDocWidth,muDocHeight); 
RectRgnCtheOf fScrHandle^^.gPort^.visRgn, 

theOf fScrHandle^^.gPort^ .portRect); 
RectRgnCtheOf fScrHandle^^ .gPort^ .clipRgn, 

theOf f ScrHandle^^ .gPort^.portRect?; 
EraseRect(CtheOf f ScrHandle^^ .gPort^ .portRect); 
SetRect(myHCRect,@, 0, 512, 342); 
CopyBi tsCHCBi ts, theOf fScrHandle**.gPort* .portBits, 

HCRect, myHCRect, srcCopy, NIL); 
HUnlockCHandleCtheOf f ScrHandle)); 

END; (GetHCBitMap) 


PROCEDURE AdjustCursor ; 

(AdjustCursor changes cursorRgn to the region that 
contains the cursor. As soon as the cursor moves out of 
cursorRgn, we get an event and can change the cursor and 
cursorRgn again. cursorRgn is either the content region 
of our window or the region containing everything BUT the 
content region of our window.) 


VAR 
mouseP t : Point; 
myWinContRect: Rect; 
myWinContRgn: RgnHandle; 
deskRgn: RgnHandle; 
handHd1 : CursHandle; 
BEGIN 
SetPortCmyWindow2; 
GetMouse(CmousePt); 
LocalToGlobal(mousePt); 
myWinContRgn := NewRgn; 


(Calculate the “work region” of our window, which is its 
content region minus the scroll bars and grow icon. 
This is the region within which we want the cursor to 
change to HyperCard’s browse tool, and outside of which 
we want it to be an arrow.) 
WITH WindowPeek(myWindow)* .contRgn^^ .rgnBBox DO 
SetRect(myWinContRect, left, 
top, 
right - 15, 
bottom - 15); 
RectRgn(myW inContRgn, myWinContRect); 
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IF PtInRectCmousePt,myWinContRect) THEN 
BEGIN 


(The cursor is in the work region of our window. Set 
to browse tool.) 


handHdl := GetCursor(browseToo1); 
IF (handHd] «€ NIL) THEN 

Se tCursor ChandHd1 ^^) 
ELSE 


(Set to arrow if can’t find browse tool resource.) 
InitCursor ; 


(Set the cursor region equal to our window’s work 
region.) 


SetEmptuRgn(cursorRgn); 
CopuRgn(muWinContRgn,cursorRgn); 
END 


ELSE 
BEGIN 
(The cursor is outside our window. Set to arrow.) 
InitCursor; 
(Get the current desktop region.) 
deskRgn := GetGrauRgn; 


(Set cursorRgn to the desktop region’s bounding box. 
It E important to add the menu bar area to cursorRgn 
too. 


SetRectRgn(cursorRgn, deskRgn^^ .rgnBBox. left, 
deskRgn*^^ .rgnBBox. top, 
deskRgn** .ngn8Box .r ight, 
deskRgn** .rgnBBox. bottom); 


(Punch out our window's content region from the big 
region.) 


DiffRgnCcursorRgn,myWinContRgn, cursorRgn); 
END; 
DisposeRgn(myW inContRgn); 
END; (AdjustCursor) 


BEGIN (Main Program) 
(Check the HyperCard version. Must be 1.2 or greater.) 
IF GetHCVersion < ‘1.2’ THEN 
FailC'Sorry, must have HyperCard 1.2 or greater. /); 


(Save thy grafPort upon enter ing!) 
GetPor tCHCPor t); 

{Check and reset our environment.) 
CheckParamCount; 
FlushEventsCevergEvent,0); 
InitCursor; 


(Find out what kind of machine we're running on.) 


envError :- SysEnvirons(1, theEnv); 
IF CenvError € noErr) THEN 
FailC'SysEnvirons call failed.’); 


(Convert HyperTalk input parameters for use here.) 


ZeroToPas(CparamPtr^ .params[1]*,wlitle); 
ГегоТоРаѕ(рагатР іг“ .рагатѕ [21^ ,wT); 
ZeroToPas(CparamPtr^ .рагатѕ (31°, wL); 
ZeroToPas(paramPtr~*.params[4]*,wB); 
ZeroToPas(CparamPtr^.params[5]^ ,wR); 
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wTop := INTEGERC(StrToNum(wT)); 
шегі := INTEGER(StrToNum(wL)); 
wBottom := INTEGER(StrToNum(wB)); 
wRight := INTEGER(StrToNum(wR)); 


(If window size parameters are too small or illegal, set 


the window to a predefined minimum size.) 


IF CCwRight - wleft) < smallestWidth) THEN 


wRight := wleft + smallestWidth; 


IF CCwBottom - «Тор) < smallestHeight) THEN 


wBottom := wTop + smallestHeight; 


(Make sure the user is not trying to draw the window off 


the screen or under the menubar. } 


SetRectCwRect, wLef t , wTop, wRight,wBottom); 
IF NOT OnAScreenCwRect) THEN 


FailC'You are trying to draw your window off the 


screen! ^); 
(Get the bounds of the desktop.) 


screenRect := GetGrayRgn** .rgnBBox; 


(If we have a small screen, make a note of it so we can 
hide the card window during context switches under 


MultiF inder. } 


ZeroToPasCEvalExpr( ‘item 3 of the screenRect’)* ,widthStr); 
screenWidth := INTEGERCStrToNumCwidthStr22; 
ZeroToPasCEvalExprC'item 4 of the screenRect^)^, 


heightStr); 


screenHeight := INTEGERCStrToNumChe ightStr22; 
IF (screenWidth = 512) AND CscreenHeight = 342) THEN 


smallScreen := TRUE 
ELSE 
snallScreen := FALSE; 


HideWindoids; 


IF MenuBarHeight > 0 THEN 
menuWasHidden := FALSE 
ELSE 
menuWasH idden 


TRUE; 
theOf fScrHandle := Of fScrHandleCNewHand le 


(SizeOf COf FScrRecord))); 


IF MemError © noErr THEN 
FailC'Out of memory. Buy more. ’); 


myDocWidth := HCWidth + padding; 
myDocHeight := HCHeight + padding; 


MoveHH i CHandleCtheOf fScrHandle)); 
HLockCHandleCtheOf fScrHandle)); 


WITH theOffScrHandle^^ 00 


BEGIN 
docWidth := myDocWidth; 
docHeight := myDocHeight; 
END; 
Ge tHCBi Мар; 


(Draw the window! } 


myWindow := NewWindow(@wRecord,wRect, 


wTitle, TRUE, zoomDocProc, 
WindowPtrC- 12, TRUE, 1); 


IF (muWindow = NIL) THEN 
BEGIN 
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ShowWindoids; 


FailC'Not enough memory to draw window. ^2; 


END 
ELSE 
BEGIN 


(This is for scrolling. Stay tuned....) 
SetWRef ConCmyW indow, LONG INTCtheOf f ScCrHandle2); 


InitBlitCmyWindow); 
DrawGrowIcon(myWindow); 


theScrollHandle := ScrollHendleCNewHandle 
(SizeOf (ScrollRecord2)); 


IF MemError © noErr THEN 


FailC'Out of memory. Buy more. ’); 


(Draw horizontal and vertical scroll bars in our 


window.) 


hScroll := CreateHScrollBar(muWindow,0,0, 


myDocWidth, 
LONGINTCtheScrolHandle)); 


vScroll := CreateVScrollBar(myWindow,9,0, 


myDocHe ight, 
LONGINT(theScrollHandle)); 


HiliteScrollBars(muWindow); 


DrawContents(muWindow); 


SetRect(dragRect,screenRect.left + 4, 
screenRect.top, 
screenRect.right - 4, 
screenRect.bottom - 4); 
largestHeight := screenRect.bottom - screenRect.top; 
largestWidth := screenRect.right - screenRect.left; 
SetRect(winSizeLimits,smallestwidth, 
smallestHeight, 
largestwidth, 
largestHeight); 


HCRefresh := 
cursorRgn := NewRgn; 
inBackGround := FALSE; 
DoneFlag := FALSE; 
REPEAT 


‘Go to this card’; 


(Call WaitNextEvent, if available. Otherwise call 


GetNextEvent.) 


IF hasWaitNextEvent THEN 
HaveEvent := WaitNextEvent(everuEvent, 


ELSE 
BEGIN 


muEvent,30,cursorRgn) 


HaveEvent := GetNextEvent(everuEvent,muEvent); 


AdjustCursor ; 
END; 
IF HaveEvent THEN 
BEGIN 


IF CmyEvent .what = app4Evt) THEN 


(Pre-process app4Evt’s fed to us by MultiFinder.) 


CASE BSR(ngEvent . message, 24) OF 


MouseMovedEvt: 
AdjustCursor ; 


SuspendResumeE vt : 
BEGIN 


myEvent.what := activateEvt; 


(Resume event.) 


IF CBANDCmyEvent.message, SuspendEventMask) © 


0) THEN 


inBackground : 


ELSE 


- FALSE 
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(Suspend event.) 
inBackground := TRUE; 


myEvent.message := LONGINT(muWindow); 
END; (SuspendResumeEvt) 


END; (CASE BSR) 
END; (IF HaveEvent) 


CASE muEvent.what OF 


mouseDown: 
BEGIN 


partCode := FindWindow(mygEvent . where, whichWindow); 


IF (whichWindow = myWindow) THEN 
BEGIN 


(Deal with mouse hits to our window.) 
CASE partCode OF 


inDrag: 
BEGIN 


SelectWindow(whichWindow); (DragWindow bug) 


DragW indowCwhichWindow, myEvent . where, 
dragRect); 
SendCardMessageCHCrefresh); 
AdjustCursor; 
END; 


inGrow: 
IF StillDown THEN (GrowWindow bug) 
BEGIN 
oldSize := whichWindow^ .portRect; 
newSize := GrowWindow(whichWindow, 
myEvent where, 
winSizeLimits); 
IF (newSize € 0) THEN 
BEGIN 
InvalScroll(whichWindow); 
SizeWindow(whichWindow, 
LOWORD(newSize), 
HIWORDCnewSize), FALSE); 
InvalContentsCwhichWindow, oldSize); 
DrawGrowIcon(whichWindow); 
MoveScrollBars(whichWindow; 
END; (IF newSize) 
END; (IF StillDown) 
END; (inGrow) 


inZoomIn, inZoomOut : 
BEGIN 
IF (TrackBoxCwhichWindow, 
myEvent .where, 
par tCode)) THEN 
BEGIN 
InvalScrollCwhichWindow); 
ZoomIt(whichWindow,partCode, 
myEvent .where); 
InvalContents(whichWindow,oldSize); 
DrawGrowIcon(whichWindow); 
MoveScrollBarsChichWindow); 
END; (IF TrackBox) 
END; (inZoomIn, inZoomOut) 


inContent: 
BEGIN 
SetPor tCwhichWindow); 
eventPoint := myEvent.where; 
Global ToLocalCeventPoint); 
controlCode := FindControlCeventPoint, 
whichWindow, 
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whichControl); 
ClipRectCwhichWindow* .portRect); 
IF CcontrolCode = inThumb) THEN 
ScrollWithThumbCwhichControl, eventPoint) 
ELSE IF Ссопіго1Соде © 0) THEN 
dummy := TrackControlCwhichControl, 


eventPoint, 
eMyScro11); 
END; (inContent) 
inGoAway: 
BEGIN 
IF CTrackGoAway(CwhichWindow, myEvent.where)) 
THEN 


DoneFlag := TRUE; 
END; (inGoAway} 


END; (CASE partCode) 
END; (IF whichWindow = myWindow) 
END; (mouseDown) 


activateEvt: 
BEGIN 
IF (WindowPtr(myEvent.message) = myWindow) THEN 
BEGIN 
SetPort(myWindow); 
ClipRect(myWindow^ .portRect); 
DrawGrowIcon(myWindow); 
IF inBackground THEN 
BEGIN 
(We've been sent behind another application 
under MultiFinder, so deactivate the scroll 
bars and show the menubar if it was hidden.) 
DeactivateCmyWindow): 
IF smallScreen THEN 
ShowH ideCW indowP tr CHCPor t ), FALSE); 
IF MenuBarHeight = @ THEN 
BEGIN 
sendHCMessage( ‘show menubar’); 
menuWasHidden := TRUE; 
END 
ELSE 
menuWasHidden := FALSE; 
END 
ELSE 
BEGIN 
(We've been brought to the front under Multi- 
Finder, so reactivate the scroll bars and 
hide the menubar if it was hidden before.) 
ShowHideC(WindowPtrCHCPor t), TRUE); 
IF menuWasHidden THEN 
SendHCMessage( ‘hide menubar’); 
DrawControls(myW indow); 
HiliteScrollBarsCmyWindow); 
FlushEventsCevergEvent, 2); 
END; (IF inBackground) 
END; (IF WindowPtr) 
END; (activateEvt) 


updateEvt: 
BEGIN 
(Handle updates to our window.) 
IF (WindowPtr(myEvent.message) = myWindow) THEN 
BEGIN 
(Always do this stuff) 
SetPor t(myW indow); 
Beg inUpdate(myW indow); 
ClipRect(myWindow*.portRect); 
DrawGrowIcon(mngWindow); 


(Always do this stuff under single Finder but 
only if in foreground under MultiF inder) 


IF NOT inBackground THEN 
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BEGIN 
HiliteScrollBars(muWindow); 
DrawControls(muWindow); 
AdjustCursor ; 

END; 


(Always do this stuff) 


DrawContents(myW indow) ; 
EndUpdate CmyW indow ); 
END (IF myEvent.message} 


(Handle updates to HyperCard’s card window.) 


ELSE IF CWindowPtr(myEvent.message) = 
WindowPtrCHCPor t2) THEN 
BEGIN 

SendHCMessageCHCRef resh); 


(Must zero out card window’s update region 
ourselves because the SendHCMessage call 
doesn’t do it, and we’1] wind up in an 
infinite loop if we don't.) 


BeginUpdateC(WindowPtrCHCPort?); 
EndUpdateCW іпаоиРіг СНСРог+ )); 
END; (IF... ELSE) 
END; (updateEvt) 


keyDown: 
BEGIN 


IF (BitAnd(myEvent.modifiers,cmdKey) «€ 0)THEN 
BEGIN 
charCode := BitAnd(myEvent . message, 
charCodeMask ); 
(Pressing command-spacebar toggles the menubar.) 
IF (CHR(charCode) = ° ‘) THEN 
Togg leMenuBar ; 
(Pressing command-W closes the window and exits 
the XCMD.) 
IF CCHR(charCode) = ‘w’) THEN 
DoneF lag := True; 
END; 


ND; 
END; (CASE myEvent.what) 
UNTIL (DoneFlag = True); 


(Clean up and get outta here!) 
DisposeRgn(cursorRgn); 
DisposHandleCHandleCtheOf fScrHandle)); 
DisposHand]e(Handle(theScrol lHandle)); 
CloseW indow(myW indow) ; 
SendCardMessage(HCrefresh); 
ShowWindoids; 

InitCursor; 

FlushEventsCeveryEvent 8); 

(Restore thy grafPort) 


21. 

END; (IF muWindow...ELSE) = 
END; (Main) Pend 
END. (Window) SEEDS 
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HyperChat™ 


XCMD Corner: HyperAppleTalk IV 


I sometimes think that, to most programmers, the network 
is best left to the handful of specialists that ply their craft on this 
arcane art. 

Think of the network as adding a new dimension to your 
programs, much as perspective enabled medieval artists to add 
depth and realism to their paintings. While many artists may 
have scoffed at perspective, I have no trouble believing that the 
populace was awed by its discovery. Perhaps networking will 
shine the same light as we enter the renaissance of computer 
programming. 

If you’ve been following this column over the last three 
months, you may be asking yourself, “Are we there yet?” This 
month, we tie the pieces together by introducing the rest of 
AppleTalk XCMDs. I apologize for publishing listings last 
month that you can’t really use until this month. I hope this issue 
makes up for it and in the future I will do my best to provide “soup 
to nuts” code in each issue. 

Conceptually, an AppleTalk interface can be reduced to the 
six steps: (1) Open access to the transaction protocol and allocate 
any memory that will be needed to interface to it. I chose the 
AppleTalk Data Stream Protocol(ADSP). ADSPOpen hooks us 
up to ADSP, establishes a connection listener and returns the 
connection listener’s socket address to Hypercard. NBPOpen 
initializes a data structure that we use to interface to NBP. The 
January '89 issue of this column provides the code for these 
XCMDs. 

(2) Given the address of the connection listener, register a 
name and type with the network using the name binding protocol. 
Once registered, our entity’s name and address will be listed in 
the “directory”. 

(3) If we want to be able to “dial up” other entities, we next 
perform a lookup which returns all current names in the lookup 
table which acts just like a directory. The names are returned as 
a list of items to Hypercard without their addresses. This step is 
optional, if all you expect to do is respond to requests (as in the 
case of a server), then you don’t need to know the names of the 
requesting entities. 

(4) Tocall another entity, invoke the ADSPCall XCMD with 
the entity’s name. ADSPCall extracts the network address from 
the lookup table using the routine “NBPGetAddress”. This 
technique allows us to de-couple names and addresses; your 
stacks need never be concerned with the address of an entity, the 
name is sufficient at the Hypercard script level. 

(5) Once a connection is established with another entity 
(called the remote end), you send information to that entity using 
ADSPTalk. You receive information from the remote end using 
ADSPListen. ADSPListen is the heart of the interface, in addi- 
tion to checking for incoming messages, it also monitors the 
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status of all open connections. 

(6) When the sessioncompletes,remove yourname from the 
names table using the NBPUnregister XFCN. Once unregis- 
tered, close down the interface to ADSP with the ADSPClose and 
then close down your NBP interface with NBPClose. 


—The XCMDS— 

While the process is conceptually quite simple, the amount 
of code needed to implement this interface may seem over- 
whelming. The rest of this article focuses on ADSPCall, 
ADSPTalk, ADSPListen and ADSPHangup. Information on 
both NBP and the open and close xcmds are available in that last 
two installments of this column as well as in recently published 
literature from APDA. 


(1) ADSPCall 

ADSPCall (listing 1) first extracts the address of the entity 
from the lookup table using NBPGetAddress. If you pass it the 
name of a currently visible entity, you have a reasonable assur- 
ance that the call will complete. 

Upon retrieving the address, adspcall walks the connection 
list checking to see if aconnection already exists with the remote 
end. If not, it creates a connection by calling DSPCreate. 

Outgoing calls are placed asynchronously, control is passed 
back to Hypercard while the call completes in the “background”. 
Asynchronous communications pays big dividends, adspcall 
attempts to establish the connection as many times as you request 
in the retry field. Waiting for a call to complete can “hang” the 
system, a particularly uncomfortable state for the user. If for any 
reason, the remote end has gone off line, Hypercard won’t be 
stuck with an unbearable delay waiting for the call to timeout. 

Outgoing calls, like all other transactions on the network, 
must be monitored by the listener. ADSPListen detects when the 
remote end picks up the phone. 

To invoke ADSPCall from your script, use the following 


command line: 

— get the name of the entity from the lookup table. 
- We let HyperAppleTalk handle the defaults for 

- retry, interval and buffer size. 


— The two above globals will have been initialized by 
- NBPOpen and ADSPOpen respectively. 


global globalNBPData, globalADSPData 
ADSPCall theEntity 


(2) ADSPTalk 
Once a connection is established with a remote end, we can 
send messages to that entity. Like ADSPCall, ADSPTalk uses 
NBPGetAddress to get the address given a name. Because 
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NBPGetAddress returns 0 if the name had no corresponding 
address in the lookup table, we can determine whether we have 
a connection to the remote end. ADSPTalk scans the connection 
list to match the address with that of an entity in our connection 
list (pointed to bey adsp^.ends). AdspTalk calls DSPTalk 
(covered last month) to send the information. Outgoing mes- 
sages are also sent asynchronously so that the user is not made to 
suffer any delays while the transmission completes. 

Like ADSPCall, the method of invoking ADSPTalk is 


straightforward: 

- *"theEntity^ is the name of the remote end that you 

- called using ADSPCall and the card field contains the 
— data that you wish to send to the remote end. 


global globalNBPData, globalADSPData 
ADSPTalk theEntity, card field “outgoing message” 


(3) ADSPListen 

The quality of any conversation depends more on the skill of 
the listener than that of the talker. This is no less true for the 
network - talking is the easy part, the listener does the hard part. 
Like any good listener, ADSPListen must perform several tasks 
at once — (1) Answer incoming calls, (2) Monitor the status of 
outgoing calls, (3) Receive incoming messages and (4) periodi- 
cally check the status of each connection. 

Putting ADSPListen in the idle method of a card or stack 
provides a method for periodically checking up on each connec- 
tion. 

For each established connection an entry exists in our 
adsp^.ends list. While most of the data stored in the connection 
(cn) block is for our own use, the network keeps us apprised of 
the connection’s status via two records: the parameter block (pb) 
and the connection control block (ccb). The parameter block 
behaves as it would for any low-level I/O on the Macintosh, it is 
the interface to the ADSP device driver. The connection block 
is used by adsp to keep us up to date on the status of each 
connection. In essence, we relinquish control of the parameter 
block and the connection control block to ADSP. The rest of the 
structures in the connection data are for our own use. 

To determine what is going on in any connection, we check 
the state field in the connection control block. The following 
States are currently supported (see listing 2 for the corresponding 
code): 

sClosed: The connection went down for some reason or 
other. At this point, we have no choice but to Hang up. 

sOpen: A connection opens in stages. When we first create 
or detect an opening connection, we set the mode to NOP 
indicating the connection is only “half open”. A half open 
connection is one in which only one of the two ends is ready. 
Receiving the sOpen state from the remote end informs us that 
our connection is now open. 

A connection that is already open signals that it’s closing 
with the “eClosed” message. If a connection is closing, hang up 
On it. 

The next two tasks, talking and listening, are monitored by 
Checkmessages. Recall that ADSPTalk queues outgoing calls; 
they complete some time in the future. Similarly, incoming 
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messages can complete at any time. To determine whether any 
incoming or outgoing messages need attention, we issue a Status 
call to adsp. The ioCrefNum field of the dspParamBlock in 
checkMessages gets the driver number of the adsp driver. The 
ccbRefnum field gets the connection number of the connection 
we are checking. 

The status call is issued synchronously, we must wait for it 
to complete before testing the status of a connection. If 
recvQPending is not 0, we have an incoming block of data. On 
input, we call ReadADSPData which will accumulate the data 
into the connection's input buffer until ADSP signals that there 
is no more data with the end-of-message flag (eom). 

ReadADSPData will read data from the connection's input 
buffer into the handle we stored in conn^.inbuf (see listing 3). 
Accumulating data is a simple task : resize the handle by the 
number of bytes that we need to read in (given to us by adsp in 
recvQpending. If recvQpending is 0, there are no bytes to read). 
Once the handle is resized, point to the old end of the handle, and 
read the data directly into that are in memory. The read returns 
the exact number of bytes read in. If that number differs from 
recvQPending (under ordinary circumstances this won't hap- 
pen), then resize the handle to reflect the actual number of bytes 
read in. 

After reading the data, we check the end-of-message flag 
(eom) which ADSP sets only after it sends the last block of the 
message down stream. If eom is set, there is no more data to read. 
We can now send the data back to hypercard. If we know the 
name of the connection, we send it back to hypercard via the 
‘ADSPCaller’ global container. This gives your stack a way of 
determining who sent the input data. The data itself is put in the 
hypercard container, 'HyperADSPData'. Once the data and 
name have been reported to Hypercard, we can optionally send 
a message back, perhaps to invoke some special input process- 
ing. If the connection stored a message in its ‘callme’ field, we 
now invoke that message via a callback. 

Monitoring outgoing calls is a bit simpler. If the 
connection's sendQPending field is not 0, we still have outgoing 
data in the output buffer. In this case, don't do anything. If on 
the other hand, the send queue has emptied out and there was data 
in it (the connection outbuf field is not nil), then dispose the 
memory currently occupied by the output data. 

The last task that ADSPListen must handle is responding to 
incoming calls. It does this by calling its respondtoListen Proce- 
dure. Ifaconnection request is pending, the connection listener's 
ioResult will be set to noErr (a negative result means an error 
occurred, a positive result means that no connection requests are 
pending, the listener still has its ears to the wall). 

If a connection request is pending, we can open up a 
connection to the remote end whose address is passed in the 
remoteCID field. Once the connection is established,we can try 
to discover its name by issuing a call to NBPGetName with the 
pending connection's name. Knowing the name of an incoming 
caller is optional so we don't take extraordinary efforts to 
discover the name. If however, you needed the entities name (as 
in the case of a game), then you can do a lookup if NBPGetName 
turns up empty-handed. This is an advanced feature and, in the 
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interest of space, I've omitted it. If you absolutely need this 
capability, drop me a line. 

Once the pending request is serviced, the connection listener 
can put its ear back to the wall by requeuing the connection 
listener call. The information needed to queuea listening request 
is already stored in the connection listener's parameter block 
(adsp^.pb). Requeuing the request becomes a simple call to 
PBControl with the connections parameter block. 

The following script, added to your card, will do the trick: 


on idle 


global globalNBPdata, globalADSPData 
global adspCaller - name of the caller global HyperADSPData 
— where incoming data goes 


ADSPListen "ShowData"^ 
end idle 


— Show data is the method to invoke to handle 

- incoming data. Assuming that we have a card field 

- named "show me^, the following method will display the 
— incoming message: 


on ShowData 
global HyperADSPData 


put HyperAdspData into card field “show me" 
end showdata 


(4) ADSPHangup 

We’ ve already seen how to detect and respond to a connec- 
tion hanging up on us. Use ADSPHangup (listing 4) to inform the 
remote end that the connection is going down. Once again, the 
drill is the same: get the address from the lookup table, check to 
see that a connection exists with this entity and call DSPHangup 
to inform the entity that the connection is going down. We don't 
remove the connection from the connection list at this point 
because we have to wait for the remote end to acknowledge our 
disconnection request. ADSPListen receives this acknowledge- 
ment in the form of an eClosed message. Once closed, we can 
tear down the connection and deallocate its memory (dspRe- 
move). 


- A simple script for hanging up 8 connection 


on Disconnect 
global HyperADSPData, globalNBPData 


ADSPHangup theEntity 
End Disconnect 


You now have a reasonably complete interface to Ap- 
pleTalk. ADSP and NBP both offer more features than I’ve been 
able to show you in a short time. Notably, the out of stream and 
forward reset features of ADSP enable some very powerful 
enhancements to the basic protocol. I chose not to discuss these 
features in this series because the average application can get by 
quite well without them. If, however, you are writing a network 
server in Hypercard, you may want to explore these features in 
more detail. I will be happy to present the code for a full 
implementation of ADSP. In keeping with the spirit of MacTu- 
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tor, contact me immediately to report any bugs in the code. I can 
be reached through this Magazine or on AppleLink (N0735) or 
MacNet. 

Next month, I'm going to switch gears back into low and 
explore the file manager from within Hypercard. 


Listing 1: ADSPCall.p 
CXooooooooooooeooopoboopobocoooobeeex ) 
(*f ile: ADSPCall.p х) 
(* *) 
(* Establish a connection with *) 
(* the entitu whose name is *) 
(* passed as a parameter. *) 
* 


( *) 
(* params[1] = Name of entitu*) 

(* params[2] = listen message *) 
(* params[3] = number of retries*) 
(* params[4] = retru interval *) 
(* params[5] = Input buffer siz*) 
(* params[6] = Output buffer siz*) 


(* х) 
(* If already connected, just *) 
(* return with noErr x) 
(* *) 
(* Defaults: х) 
(ж Input Buffer = 578 х) 
(* Output Buffer = 578 *) 
(* Retru count = 0 х) 
(ж Retru interval = 0 х) 
(* Out: the Result ::= error Ж) 
(*message, emptu if none. x) 
(* х) 
(Ж ------------Х) 

(* By: Donald Koscheka *) 
(* Date: 9-Jan-89 *) 
(* All Rights Reserved *) 
(* *) 


625122525452522252525442222445442522 


(ХХХХХХХХХХХХХЕХХХХХХХХХХХ ХХХ ХХХ 
Build Sequence 


pascal ADSPCall.p -o ADSPCall.p.o 

link -m ENTRYPOINT -rt XCMD=1302 -sn Маіп-АО5РСа119 
ADSPCall].p.od 
“(libraries)“Interface.o д 
-o YourStackNameHere 


XX£XXXXXXXXXXXXXXXXXXXXXXKEXXXXKXKXKXX) 


($R-) 
($S ADSPCa11) 
UNIT Koscheka; 


(YYXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXE) 


INTERFACE 
(Y33355 35 3555535553 ххх жэ) 


Uses MemTupes, QuickDraw, OSIntf, 
ToolIntf, PackIntf, HuperXCmd, 
Applelalk, ADSP, adspxcmd; 


Procedure EntruPoint( paramPtr : XCmdPtr 2; 
( ЖЖЖЖЖЖЖЖАХЖАЖАЖАЖЖЖХАЖЖЖЖЖЖАЖЖАЖЖЖЖЖЖЖ%Х УУ 


IMPLEMENTATION 


(YXXXX1X1X21XX1XXXFXXXXX1XXXXXXXXXXKXXKXK) 


ТҮРЕ Str31 = String[31]; 


PROCEDURE ADSPCa11( paramPtr: XCmdPtr ); FORWARD; 
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Procedure EntruPoint( paramPtr : XCmdPtr ); 


Begin 
ADSPCa11( paramPtr ); 
End; 
Procedure ADSPCallC paramPtr : XCmdPtr ); 
VAR 
adsp : ADSPPtr; 
error, terr: OSErr; 
inBufSiz : Integer; 
outBufSiz : Integer; 
retry : Integer; 
interval  : Integer; 
eAddr : AddrBlock; 
cn : CBPtr; 
nbp : NBPPtr; 
found : BOOLEAN; 


($I XCmdGlue. inc ) 
($I XCMDADSP. inc ) 


(Qeoeoeeeoeeoooocecocoeobococboee ce ec eee) 


BEGIN 
error :* noErr; 
found := TRUE; (*** true if already established ***) 


WITH paremPtr^ ро 
BEGIN 
IF CparamCount «€» 0) AND Cparams(1]^ © NIL) THEN 
BEGIN 
adsp := ADSPPtr(RetrieveDataC ‘GLOBALDSPDATA’ )); 
IF adsp O NIL THEN 
BEGIN 
adsp^.checkPoint := RECEIVING; 


(**** Before we go too far, let’s ***)} 
(*** look at some of the settings ***) 
(*** set the retransmit count хаж) 
IF рагәпв (31 O NIL THEN 

retry := StringloSHort( params[3]^ ) 
ELSE 

retry := 9; 


(*** Set the retransmit interval ***) 
IF рагамѕ (4) © NIL THEN 

interval := StringToSHort( params[4]* ) 
ELSE 

interval := 0; 


(*** Set the input buffer size ***) 
IF params[5] € NIL THEN 

inBufSiz := StringToSHort( params[51^ ) 
ELSE 

inBufSiz := ATPBSIZE; 


(*** Set the output buffer size ***) 
IF params(6] «€ NIL THEN 

outBufSiz := StringToSHortC paraems[61^ ) 
ELSE 

outBufSiz :- ATPBSIZE; 


(жжж (1) Get the entity’s address ***} 
HLockC HandleC params[11) ); 

eAddr := NBPGetAddress( params[1]^ ); 
HUnlockC HandleC params[1] ) ); 


(*** Walk through the connection хх) 
(*** list to see if the connection ***) 
(*** already exists. xxx) 


IF LongInt(eAddr) € 0 THEN 
BEGIN 

cn := adsp*.ends; 

found := FALSE; 
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WHILE CNOT found) DO 
IF cn = NIL THEN 


found := TRUE 

ELSE 

IF LongInt( eAddr ) = LongInt( cn^.adr ) THEN 
found := TRUE 

ELSE 


cn := cn*.next; 


(*** If connection already exists ***) 
(*** cn will not be NIL so we won't ***) 
(*** have to reconnect the two ends, ***) 
(*** just fall out, otherwise, try to***) 
(*** make the connection. xxx) 


IF cn = NIL THEN (*** establish connection **x) 
BEGIN 

cn^.remName:- NBPGetName( eAddr ); 

cn := DSPCreateCeAddr, inBufSiz, 

outBufSiz,retry, interval, params[2] ); 
IF cn € NIL THEN 
BEGIN 
cn^.remName :- NBPGetName( eAddr ); 


(*** try to discover the name***) 
IF cn^.remName = NIL THEN 
BEGIN 
nbp := NBPPtr(Retr ieveDataC ' GLOBALNBPDATA ^5); 
IF nbp <> NIL THEN 
BEGIN 
SendCardMessage( 'DoALookUp ^); 
cn^.remName :- NBPGetNameC eAddr ); 
END; 
END; 


(*** Now “dial for dollars” ***) 
WITH cn^.dspPB DO 


BEGIN 
ioCRefNum := adsp^.dspRefNum; 
ccbRefNum := cn^.ccbRef; 
csCode := dspOpen; 
ocMode := ocRequest; 
ioCompletion:= NIL; 
remoteCID :- 0; (*** don’t know this get**x) 


localCID := 0; (%%% adsp allocates id***) 
remoteAddress:= eAddr; 
filterAddress.aNet := 
filterAddress.aNode := 
filterAddress.aSocket:- 0: 
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SendSeq := 8; 
RecvSeq : Ø; 
SendWindow := 0; 
attnSendSeq:= 0; 
attnRecvSeq:= 0; 
oclnterval := INTERVAL; 
ocMaximum :- RETRY; 
error >= PBControlC @cn*.dspPB, ASYNC ); 
END; 
END; 


END; 
END; (CLongIntCeAddr) O 0) ) 
adsp*.checkPoint := CLOSE_OK; 
END; 
END; 
returnValue := PasToZero€ NumToStr( LongIntCerror) ) ); 
END; (*** with paramPtr^ ***} 
END; 


end. 


Listing 2: ADSPTalk.p 


(ЖЖЖЖЖАЖЖЖАХЖАЖЖЖЖХЖЖЖАЖЖЖЖЖЖЖЖЖЖЖ)) 
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(*file: ADSPTalk.p x) 

(* x) 
(* Send information to an *) 
(* established connection. *) 
(* The connection must be x) 
(* been established via the *) 


(* ADSPCALL xcmd. х) 
(ж х) 
(* In: *) 
(* params[1] = entitu name*) 
(* of the remote end. * 
(* *) 
(ж ——P*) 

(* By: Donald Koscheka *) 
(* Date: 2-Mar-89 *) 
(* All Rights Reserved *) 
(* *) 
(ж —əy T" X) 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ у 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖАЖЖЖЖЖЖЖЖЖЖЖ 
Build Sequence 


pascal -o ADSPTalk.p.o ADSPTalk.p 

link -m ENTRYPOINT -rt XCMD=1385 -sn Main-ADSPTalkà 
ADSPTalk.p.oó 
“{libraries)“Interface.o д 
-o YourStackNameHere 


3o XxoXooororoookcoororerorororororotorooororoo У 


($R-} 
($5 ADSPTalk) 
UNIT DummyUnit; 


(ЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖХ У 


INTERFACE 
(YXXXXXXXXXXXXXXX33333XXKXXXX) 


Uses MemTypes, QuickDraw, OSIntf, 
ToolIntf, PackIntf, HuperXCmd, 
AppleTalk, ADSP, adspxcmd; 


Procedure EntruPoint( paramPtr : XCmdPtr ); 


(ЖЖЖЖ) 
IMPLEMENTATION 


(YXYX1XXXXX1XXXXXXXXXXX.XXKXXXXXX) 
TYPE Str31 = String[31); 


PROCEDURE ADSPTalk( paramPtr: XCmdPtr 2; FORWARD; 


Procedure EntryPoint( paramPtr : XCmdPtr ); 
Begin 
ADSPTalkC paramPtr 2; 
End; 


Procedure ADSPTalkC paramPtr : XCmdPtr ); 
VAR 
adsp : ADSPPtr; 


error : OSErr; 
eAddr : AddrBlock; 
cb : cbPtr; 


($1 XCmdGlue. inc ) 
($1 XCMDADSP. inc ) 


BEGIN 
error := noErr; 
әсер := ADSPPtr(RetrieveDataC ‘GLOBALDSPDATA’ )); 
IF Cadsp € NIL) 
AND CparamPtr^.params[1] © NIL) 
AND CparamPtr*.params(2] «> NIL) THEN 
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BEGIN 
adsp~.checkPoint := RECEIVING; 
(*** (1) Get the entity’s address xxx) 
HLockC paramPtr^.params[1] ); 


eAddr := NBPGetAddress( paramPtr^.params[1]^ ); 
cb := adsp^.ends; 


(*** (2) Find entity in connection list***)} 


IF LongIntC eAddr 2 «€ 0 THEN 
WHILE cb © NIL DO 
IF CLongInt(cb*.adr )=LongIntCeAddr 2) 
AND (cb*.ccb.state=sOpen) THEN 


BEGIN 
error :- DSPTalk(€cb, paramPtr^.paramsí2] ); 
cb := NIL; 

END 

ELSE 


cb := cb^.next; 


adsp*.checkPoint := CLOSE OK; 
HUnlock(€ HandleCparamPtr^.params[11) 2; 
END; 
paramPtr^.returnValue := PeasToZeroC NumToStrC LongIntCerror?) 
2); 
END; 


end. 


Listing 3: ADSPListen.p 


( ЖЖЖЖЖЖЖАЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
(*file: ADSPListen.p 50 

(* *) 
(* Perform the following: *) 
(* (1) Listen for incoming *) 
(Жса116 on the connection *) 
(* listener *) 
(* (2) Check to see if any *) 
(*outgoing calls have been*) 


(*answered *) 
(* (3) Check connections &) 
(*for incoming data *) 
(* (4) Check connections for*) 
(*attention messages £) 
(* х) 
(* In: *) 


(x perams[1] = name of *) 
(* message to call hupercard*) 
(* with on inconing data *) 


(* *) 
(* Defaults: *) 
(* container = HyperADSPData*) 
(* message = none. х) 
(ж х) 
(* ------- %) 

(*A11 Rights Reserved *) 
(* *) 
(x -------%) 

(* By: Donald Koscheka *) 
(* Date: 2-Mar-89 *) 
(ж All Rights Reserved *) 
(* *) 
(ж ---------<Х) 


( ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ у 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖАЖЖЖЖХЖХЖ 
Build Sequence 


pascal -o "(hpo)"ADSPListen.p.o “(adsp)*ADSPListen.p 
link -m ENTRYPOINT -rt XCMD=1303 -sn Main=ADSPListend 
ADSPListen.p.oó 
“(libraries)“Interface.o д 
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-o YourStackNameHere 


XKIXXXKKEXKXXXXXXXKEXKXZEXXXXXKXKX) 


($R-) 
($S ADSPListen) 
UNIT Koscheka; 


(ЖЖЖЖАЖЖАЖЖАЖЖАЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖХ у) 


INTERFACE 
(ЖЖЖЖ) 


Uses MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, Hu- 
perXCmd, AppleTalk, ADSP, adspxcmd; 


Procedure EntruPoint( paramPtr : XCmdPtr ); 


(xxoooooeeoeceeoboooopoeceeoeooeeegec) 


IMPLEMENTATION 


(ХХХ ж ж ж ж ЖЕЖ) 
ТҮРЕ Str31 = String[31); 


PROCEDURE ADSPListenC paramPtr: XCmdPtr 2; FORWARD; 
Procedure EntryPoint( paramPtr : XCmdPtr ); 
Begin 
ADSPListenC paramPtr ); 
End; 


Procedure ADSPListen( paramPtr 
VAR 

myFlags : SignedByte; 
( flags from incoming unsolicited message } 

edsp : ADSPPtr; ( pointer to ADSP Control block) 


: XCmdPtr ); 


error : OSErr; 
err : OSErr; 
cn,nn : cbPtr; ( pointers to established conections) 


nbp : NBPPtr;( pointer to the memory NBP interface) 
mybPtr : Ptr; — ( used for getting and setting flags) 


($I XCmdGlue. inc ) 
($1 XCMDADSP. inc ) 


PROCEDURE RespondToL isten; 

655525222222222222223242222243229 
(* If the connection listener %) 
(* has completed, then someone *) 
(* is trying to call. If we can*) 
(* initialize a connection, х) 
(* acknowledge receipt of call.*) 
EFF 2225552559252 3 9529 5935523395 3m) 


VAR 
err : Integer; 
conn : CBPtr; 
tH : Handle; 
BEGIN 


IF adsp*.pb.ioResult = noErr THEN 

BEGIN — (*** We Have an incoming call. ххх) 
(*** Create a connection end to***} 

(*** the caller and set the ***) 

(*** state to active indicating ***) 

(*** the connection is accepted***) 

conn := DSPCreateCadsp* .pb.remoteAddress, 

ATPBSIZE, ATPBSIZE, RETRY, INTERVAL ,NIL ); 


IF conn © NIL THEN 
WITH conn^.dspPB DO 


BEGIN _ (*** accept the connection request***) 
ioCRef Num := adsp* .dspRefNum; 
ioCompletion := NIL; 
csCode := dspOpen; 
ocMode :* ocAccept; 
ccbRef Num := conn^ .ccbRef ; 
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END; 


remoteCID := adsp^.pb.remoteCID; 
localCID = 0; 

remoteAddress = adsp^.pb.remoteAddress; 
filterAddress.aNet = 0; 
filterAddress.aNode := Ø; 
filterAddress.aSocket := @; 

RecvSeq := 0; 

attnRecvSeq := Ø; 

SendSeq >= adsp* .pb.SendSeq; 
attnSendSeq ‚= adsp* .pb.attnSendSeq; 
SendWindow ‚= adsp^.pb.SendWindow; 
ocInterval := INTERVAL; 

ocMaximum := RETRY; 


err := PBControl( 8conn^.dspPB, ASYNC ); 


(*** Call back Hypercard to inform ***) 
(***it of an incoming call. Xxx) 


conn^.remName := NBPGetNameC adsp^.pb.remoteAddress 


END; 


(*** Reset connection listener to**x) 

(*** wait for more calls ххх) 

err := PBControl( @adsp*.pb, ASYNC ); 
END 


PROCEDURE ReadADSPData( conn:CBPtr; cnt: Integer; callMe:Handle 
9: 


«ТТТТТТІТТТТІТТІТТТТІТТТІТІУ 
(* Poll the connection to x) 
(* determine whether anu *) 


(* data is pending. 


If so, х) 


(* read it and pass it баск to *) 
(* hupercard via the callback*) 


(* mechanism. х) 
(ж х) 
(ж IN: х) 
(* conn : pointer to connection *) 


(* спі: num. of bytes to read *) 


(* callMe : callback method *) 
(Y21X1XXXX7XXXXXXXXXXXXXXXXXXXXXXXXX) 
VAR 

Tempb : dspParemBlock; 

err : Integer; 

temp : LongInt; 

inSize : LongInt; 

globName: Str255; 

tp Dp 

tH : Hendle; 
BEGIN 


globName:= ‘HyperADSPData’; 


WITH conn* DO 


BEGIN 


(*** read the data ххх) 
IF inBuf = NIL THEN 
BEGIN 
inBuf :- NewHandleC LongInt(cnt) 2; 
MoveHHiC inBuf ); 
HLockC inBuf 2); 
tp:= inBuf^; 
END 
ELSE (*** inBuf already allocated, add to end of it***) 
BEGIN 
HUnlockC inBuf ); 
inSize := GetHandleSizeCinBuf ); 
temp := inSize; 
inSize := inSize + LongInt( cnt ); 
setHandleSize€ inBuf, inSize ); 
MoveHHi( inBuf ); 
HLock( inBuf ); 
temp := temp + Ord4( inBuf^ ); 
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tp := Pointer(temp); BEGIN 


END; HUnlock( cn^.outBuf ); 
DisposHandle( cn^.outBuf ); 

WITH Tempb DO (*** now read the data ***) cn^.outBuf := NIL; 
BEGIN END; 

ioCRefNum := adsp^.dspRefNum; END; ( myErr o no€rr ) 

ccbRefNum := conn*.ccbRef; CheckMessages := myErr; 

csCode := dspRead; END; 

reqCount := cnt; 

dataPtr ‘= tp; (ЖЖЖЖЖЖЖЖЖХЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ У 
END; (ж ADSPListen х) 
err ‘= PBContro1¢ @Tempb, SYNC ); (ЖЖЖЖЖЖЖАЖЖХЖАЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ)) 
HUnlock( inBuf ); 

BEGIN 

IF err=noErr THEN error := noErr; 
BEGIN adsp := ADSPPtr(RetrieveDataC ‘GLOBALDSPDATA’ )); 

inSize := GetHandleSize( inBuf ); 

inSize := inSize - (cnt-Tempb.actCount); IF adsp © NIL THEN 

SetHandleSizeC inBuf, inSize 2; BEGIN 
END; adsp^.checkPoint := RECEIVING; 


cn := adsp^.ends; 
IF Cerr=noErr) AND (Tempb.eom=1) THEN 


BEGIN (***(2) Monitor status on all connections***) 
IF inBuf € NIL THEN (***Са11 back with data**x) WHILE cn © NIL DO WITH сп” DO 
BEGIN BEGIN 
IF remName © NIL THEN nn := next; 
SetGlobalC ‘ADSPCaller’, remName ); err := noErr; 
tp:= Pointer( Ord4C inBuf* ) + LongIntCinSize) ); CASE ccb.state OF ( connection states } 
tp* := 0; sClosed: err := DSPHangUp( cn ); 
SetGlobal( globName, inbuf ); ѕ0реп: 
DisposHandle( inbuf ); BEGIN 
inbuf := NIL; IF mode = NOP THEN (***connection is opening ***) 
END; BEGIN (***inform Hypercard of connect ion***)} 
SetGlobalC ‘ADSPCaller’, remName ); 
IF callMe <> NIL THEN (***Set remote-end name**x) SendCardMessage( ‘ConnectionMade’ ); 
BEGIN mode := EST; 
HLockC callMe ); END 
ZeroToPasC Pointer( callMe^ 2, globName ); ELSE 
HUnlock(C callMe ); BEGIN — (*** Check an established connection ***) 
SendCardMessage( globName ); myBPtr := @cn*.ccb.userF lags; 
END; 
END; IF BANDCmyBPtr*, eClosed)=eClosed THEN 
END; (*** read the data ***) err := DSPHangUp( cn ) 
END; ELSE 
BEGIN 
Function CheckMessages( cb : cbPtr ): OSErr; err :- CheckMessages( cn ); 
(YXYXXKXKXKIXXXXXXX1XXXXXXXXX1XXXKXXXXXXXKX) 
(* check this connection for: *) myBPtr^ := 0; ( clear user flags) 
(* (1) Completed Incoming Messages *) END; 
(* (2) Completed Outgoing Messages *) END; 
Cooooooooeororooorororororooreroroororooroooooeccex ) END; 
VAR END; ( case of connection states ) 
myErr : OSErr; 
tpb : dspParamBlock; IF err О noErr THEN error := err; 
BEGIN cn := nn; 
WITH tpb DO END; 
BEGIN RespondToListen; (*** check for opening calls ***) 
csCode := dspStatus; &adsp^.checkPoint := CLOSE. OK; 
ioCRefNum := adsp^.dspRefNum; END; (*** IF adsp © NIL ***) 
ccbRefNum := cn^.ccbRef ; 
END; peremPtr^.returnValue :- PasToZero(€ NumToStr(C LongIntCerr) ) 
myErr := PBControlC @tpb, SYNC ); 32i 
END; 
IF myErr = noErr THEN 
BEGIN end. 
(*** (3) Check for pending incoming data***) 
IF tpb.recvQPending © 0 THEN Listing 4: ADSPHangUp.p 
ReadADSPDataC cn, tpb.recvQPending, paramPtr^.params[1] 
рУ (ЖЖЖЖЖЖЖЖХАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ) 
(*file: ADSPHangUp.p *) 
(***(4) See if any write operations have completed***) (ж х) 
IF (tpb.SendQPending = Ø) AND Ccn^.OutBuf © NIL ) THEN (* Disconnect an established*) 
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(* connection and deallocate*) 
(* the data associated with*) 
(* the connection. x) 
(* х) 
(Ж In: рагамѕ 1) Name of *) 

(* the entitu to hangup on *) 


(* *) 
(* Qut: error message, х) 
(*emptu if попе. х) 
(* *) 
(* -------%) 

(*Bu: Donald Koscheka *) 
(* Date: 2-Mar-89 *) 
(* All Rights Reserved *) 
(* ж) 
(% --------Х) 


(ЖЖЖЖЖЖХЖЖЖАЖХҖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ у 


(ЖЖЖЖЖЖЖЖАЖЖХАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Build Sequence 


pascal -o ADSPHangUp.p.o ADSPHangUp .p 

link -m ENTRYPOINT -rt ХСМО-1304 -sn Main-ADSPHangUpó 
ADSPHangUp .р.од 
“(libraries}“Interface.o д 
-o YourStackNameHere 


XXXXXXXXXX1XXXXKXXKXXXXKXXXXKXXKX) 


($R-) 
($S ADSPHangUp) 
UNIT DummuUnit; 


(ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХ )) 


INTERFACE 
(Qoooooopooopoopbooooopoe AKER ) 


Uses MemTypes, QuickDraw, OSIntf, 
ToolIntf, PackIntf, HyperXCmd, 
AppleTalk, ADSP, adspxcmd; 


Procedure EntryPoint( paramPtr : XCmdPtr 2); 


(***Xxxxxxxxxxcoxx xx xxx0CXXX x) 


IMPLEMENTATION 


(YXX1XXX1K.X1XX1XXXXXXXXXXXXXXXXKXX) 


TYPE Str31 = String[31); 


PROCEDURE ADSPHangUp( paramPtr: XCmdPtr ); FORWARD; 
Procedure EntruPoint( paramPtr : XCmdPtr 2; 
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Begin 
ADSPHangUp( paramPtr ); 

End; 
Procedure ADSPHangUp( paramPtr : XCmdPtr ); 
VAR 

ədsp : ADSPPtr; 

error : OSErr; 

pb : DSPParamB lock; 

eAddr : AddrBlock; 

cb : CBPtr; 


($I XCmdGlue. inc ) 
($I XCMDADSP. inc } 
( ЖЖЖЖЖАЖЖЖЖАЖЖЖХЖЖХЖЖЖЖАЖЖЖЖХЖЖЖЖЖЖ)) 
BEGIN 
error := noErr; 
IF € paramPtr^.paramCount > Ø ) 
AND € paramPtr^.params[1] € NIL ) THEN 
BEGIN 
adsp := ADSPPtr(RetrieveDataC ‘GLOBALDSPDATA’ 2); 
IF adsp © NIL THEN 
BEGIN 
adsp^.checkPoint :- RECEIVING; 
(*** (1) Get the entity’s address ***) 
HLockC Handle(paramPtr^.params[1]) ); 
eAddr := NBPGetAddress( paramPtr^.params[1]^ ); 
cb := adsp*.ends; 


(*** match the entity to the list ***) 
IF LongIntCeAddr) «» 0 THEN 
WHILE cb € NIL DO 
IF LongIntCcb^.adr ) = LongIntC eAddr ) THEN 


BEGIN 
error := DSPHangUp(C cb 2; 
cb := NIL; 
END 
ELSE 


cb := cb*.next; 


HUnlockC HandleCparamPtr*.params[1]) ); 
edsp^.checkPoint := CLOSE OK; 
END 
END; 
peremPtr^.returnValue := PasToZero( NumToStr( LongInt(error) 
) 2 
END; 


end. bw! 
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HyperChat!M 
Menu bar XCMD 


on HyperChat 


Your wish is my XCMD 

I have two XCMD’s this month that I find quite useful. The 
first I called invisMenuBar, it makes the menubar invisible and 
still functional. It is really useful when developing on a small 
screen. The Human Interface Guidelines clearly state “don't hide 
things from the user and don’t surprise them”. So why am I 
showing you this XCMD? Firstly I would strongly object to 
people using it in a stack. It is a development/power user tool it 
may help you develop stacks and browse through other peoples 
if you havea small screen. Justlike MacsBug deviates along way 
from the guidelines but is highly useable and appropriate in it's 
context. What it does. It simply uses a callback to hypertalk to 
hide the menubar, then it sets the height of the menubar to the 
height of it's natural state. Hypercard is fooled to think that it is 
hidden so it doesn't do a menubar redraw, however when you 
have a mousedown in the menubar it accepts it and draws the 
menu. 


(* 
invisMenuBar- a sHuperCard external command 
that makes the menubar invisible uet functional. 


Written in MPW Pascal. 
Written by Fred Stauder 
@All rights reserved 1988 


pascal :Sources:XCMD:InvisMenuBar.p 

link -o AJS-60:test -rt XCMD=7004 -sn д 
Main=InvisMenuBar :Sources:XCMD:InvisMenuBar.p.o à 
o -m ENTRYPOINT 

x) 


InvisMenuBar 
segment name must be the same as the command name. 


UNIT Fred_Stauder ; 
INTERFACE 


USES MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 
PasLibIntf, HyperXCmd; 


PROCEDURE ENTRYPOINTCparamP tr :XCmdP tr); 


IMPLEMENTATION 
ТҮРЕ Str31 = String[31]; 


PROCEDURE InvisMenuBar(paramPtr :XCmdPtr); FORWARD; 
PROCEDURE ENTRYPOINTCparamP tr : ХСтаріг ); 
BEGIN 
InvisMenuBar (paramP tr ); 
END; 
PROCEDURE InvisMenuBar(CparamPtr : XCmdP tr); 
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HyperCard 


Fred Stauder 
HyperChat Editor 
Zurich, Switzerland 
Volume 5, Number 5 


XCmdGlue.inc the glue routines 
VAR menuBarHeight: Ptr; 


BEGIN 
SendCardMessage( ‘hide menubar’); 
menuBarHeight := Ptr($BAB); 
directly to the global the only way possible 
menuBarHeight* := $14; 


4 


END. 


Listing 1. 


The second XCMD allows you to change the window type. 
This is useful when you want to do a presentation and not have 
the window title visible. Or if you want to make a small window 
for a specific purpose. (fig.1.) The windowDefproc and the high 
order byte holds the window variation code. First you pass a 
parameter with the XCMD changeWindowType, that gives you 
the desired window. the types are the same as in Inside Mac V I 
p273. 


documentProc = 0 (standard document window) 
dBoxProc = 1 (alert box or modal dialog box) 
plainDBox = 2 (plain box) 

altDBoxProc = 3 (plain box with shadow) 
noGrowDocProc = 4 (document window without size) 
rDocProc = 16(rounded-corner window) 


w File Edit View Special Color 


Figure 1. 


You take the parameter, convert to a Longint, then comes the 
slightly tricky bit where you have to do bit manipulation to write 
it to the high order byte of the windowDefproc. You can get the 
window type by using the function GetWVariant. I will leave this 
as an exercise for you to write, so that once you have changed the 
window type you will be able to find out what it is through an 
XFCN. 

Diagram 1. shows how the bits are manipulated to put the 
window variant into high order byte of theWindow^.DefProc 
handle. Then I hide and show the cardwindow to update the 
screen. 
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Pointer 


Y 


ОО ОО OOFF 


Pointer 


00 00 00 ХХ 


firstMask 
BitAnd 
Stet == == XN 
Pointer BitShift +24 
kindLongint) ї 
00 00 00 ХХ -- -- -- 
Handle 
Pointer 
Y Bitor 
Pointer newWind 
FF 00 00 OO 
XX OO OO OO 
secondMask 
BitAnd 


ХХ -- -- -- 
thewindow’.def Proc 


Diagram 1. 


Listing 2. 

Written in MPW Pascal. 

Written by Fred Stauder 

ФА11 rights reserved 1988 
(* 
pascal :changeWindowType.p 
link -o Development :Demo:home -rt XCMD=7005sn д 
Main-changeWindowType :changeWindowlype.p.o -m ENTRYPOINT 
*) 


changeWindowlype name must be the same as the command name 


UNIT DummyUnit; 
INTERFACE 


USES MemTypes, QuickDraw, OSIntf, ToolIntf, PasLibIntf, 
HyperXCmd; 


PROCEDURE ENTRYPOINTCparamP tr : XCmdP tr); 
IMPLEMENTATION 


Str31 = String(311]; 
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PROCEDURE changeWindowTypeCparamPtr:XCmdPtr); 
FORWARD; 
PROCEDURE ENTRYPOINTCparamPtr:XCmdPtr); 
BEGIN 
changeW indowTgpeCparamP tr); 
END; 
PROCEDURE changeWindowTypeCparamPtr :XCmdPtr ); 
VAR 
HCWindow: WindowPtr; 
theWindow: X WindowPeek; 
tempStr: 517255; 
kind: Longint; 
newWind: — Longint; 
f irstMask : Longint; 


firstShift:  Longint; 
secondMask:  Longint; 


XCmdGlue.inc the glue routines 


BEGIN 
GetPor tCHCWindow); 
thy port 
ZeroToPas(CparamPtr^.params[1]^,tempStr); 
kind := StrToNumCtempStr); 


theWindow := WindowPeekCHCWindow); 

firstMask := BitAnd(K ind, $000000FF 5; 

firstShift := BitShift(firstMask, 24); 

secondMask := 
BitAndCLONGINTCtheW indow^ .windowDefProc), $00FFFFFF 5; 


newWind :- BitORCfirstShif t, secondMask ); 


theWindow^.windowDefProc := HandleCnewWind); 
SendHCMessage( ‘hide cd window’); 
sendHCMessage( ‘show cd window’); 
Se tPor tCHCWindow); 
thy port 
END; 
END. 


Next month I will show you an XCMD that will allow you 
to resize the card window of Hypercard such as in Fig. 1. 
Send articles ideas, comments etc to Applelink: STAUDER. 


<—. 


end HyperChat Рм 
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XCMD Corner: XCMDs in Think C "yperCcard 


Exploring XCMDs using just one development system is a 
lot like learning to play music on just one instrument. This is 
unfortunate because the Macintosh offers a virtual orchestra of 
development systems. As in learning to play a second instru- 
ment, learning a new development system often boils down to 
nothing more than learning how to transcribe the music. 

Your programming environment is your instrument (writ- 
ing a program is more like writing a piece of music than playing 
it). If you happen to own a copy of MPW you have no trouble 
using the code in this column because it’s all written for MPW. 
If you use a different development system , you’ll need to 
transcribe my listings to play on your particular development 
system. 

In the past, I’ve been terribly guilty of catering to the MPW 
clique. My reasons were perhaps not so subtle: I use MPW at 
work; I'm comfortable with it, and I know that it directly supports 
an interface to XCMDs. After purchasing a copy of MPW 3.0, 
I realized that I might be making a mistake. For starters, MPW 
requires an expensive and time consuming learning curve; per- 
haps not everyone wants to spend several hundred dollars for 
sophistication they may never need. 

Other development systems offer features that are not avail- 
able in MPW such as a high quality source level debugger. 
Unfortunately several development systems lack key capabili- 
ties like support for XCMDs. Although you might expect 
LightspeedC to support XCMDs out of the box, it doesn’t. I’m 
not sure I understand the reason, but it doesn’t matter. Adding 
XCMD support to any compiler should be a very simple job. 

Afterall, an XCMD is just another type of resource. If 
LightspeedC can create specialized resources such as window 
definitions and drivers, it already contains some of the support we 
need. 


• Setting up the project 

As luck, or design foresight, would have it, LightspeedC 
supports a generalized resource type called the “CODE” Re- 
source. CODE resource projects are created like any other 
project in LightspeedC with the exception that you specify the 
project as a code resource in the set project type dialogue (see 
figure 1). You specify most of the information that the resource 
manger wants in this dialogue. 

The custom header option requires a little elaboration. The 
standard interface to code resources branches to the entry point: 
main() . Selecting the Custom header option causes the entry 
point to be the first function in the file in which your main() is 
defined. XCMDs follow the second course as a matter of style. 

Set the resource type to *XCMD' or ‘XFCN’ according to 
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O Rpplication 7727? 
© Desk Accessory 
O Device Driver 


(8 Code Resource 


File Type 


Creator 72777 


Dd Custom Header 


Name 


Figure 1. Setting up a Code Resource using the 
Set Project Type Dialogue 


the type of Hypercard interface you want. 


* Writing the XCMD 
In LightspeedC, a code resource has the same form as a “C” 
program. You define the entry point as: 


pascal void main( paramPtr ) 


ParamPtr is a pointer to a HyperTalk XCMDBlock. From 
there, your code looks like a vanilla “С” application. The same 
restrictions apply as on all CODE resources: no globals or 
statically initialized strings. CODE resources, of any kind, have 
no knowledge of globals at build time because they can't make 
any assumptions about which application willload them! Strings 
suffer the same fate - “С” allocates statically defined strings in the 
application's global pool. You're not building an application so 
you don’t have a global pool - you must either define strings the 
hard way or load them in from the resource fork. 

Listing 1 is a simple XCMD that returns the string “Hello 
World" to Hypercard. While the code itself is wholly unimagi- 
native, it does demonstrate that the interface to Hypercard and the 
callback mechanism work satisfactorily. Anyhow there's a time 
for imagination and a time to just get things done. Porting an 
interface falls to the latter category. 

Include the header file, "HyperXCMD.h" (listing 2 ) in your 
code. This is the standard interface to Hypercard transposed for 
LightspeedC. There aren't a lot of differences between the two 
as should be the case. Nonetheless this exercise proves quite 
useful in scoping out the idioms of a particular language implem- 
entation. 
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° The Hypercard “Glue” 

You need to create a project which at the least includes 
MacTraps, your XCMD code and a special file called 
*XCMDGlue.c" (Listing 3) which interfaces (or glues) your 
XCMD to Hypertalk's callback mechanism. I took the liberty of 
translating XCMDGlue.in.c from MPW “C” to LightspeedC. 
The major difference between the MPW and Think versions of 
the glue is that I use the CallPascal function available in Light- 
speedC to jump to the subroutine pointed to by paramPtr- 
>entryPoint. Pascal routines push parameters from left to right 
and the subroutine is responsible for clearing the stack parame- 
ters. *C" pushes from right to left and the caller clears the stack. 

We know that the callback engine uses the Pascal calling 
sequence because the parameters aren't left on the stack after the 
call. Whether we push from right to left or left to right isn't 
relevant here for an obvious reason that's leftas an exercise to the 
reader. 

Add XCMDGlue.c to the project rather than including it at 
the end of the XCMDS source code as is the case with MPW. I 
like this feature of Think “C” - you keep track of the source 
modules at the project level and not at the source code level. 


• Creating the resource 

Once all modules compile,use the “Create Code Resource" 
menu option to create the code resource. LightspeedC presents 
a dialogue asking for the name of an output file. Enter the name 
of a file but not your output stack: LightspeedC completely 
erases the previous contents of both forks of the output file before 
writing out the code resource! 

Select the “smart link" option when creating acode resource. 
Your links will be slower, but your XCMDs will be quite a bit 
smaller (The example in listing 3 compiles to 12.5K with smart 
link of and 2.5K with smart link on). Of course, you can speed 
up turnaround during development by leaving this option unse- 
lected. 

That's it! Use ResEdit or Rescopy to copy the XCMD into 
your stack. Perhaps LightspeedC will release a future version of 
“C” that will build code resources directly into the target file (if 
you try this now, the entire contents of the target file will be lost). 
In the meantime, the extra step needed to copy the resource into 
your stack is a small price to pay for an outstanding development 
system. 

I hope the information in this article will help those of you 
who need to create an XCMD interface for another development 
system. The process is really rather simple and it provides you 
one of those rare opportunities in programming where you can 
get a lot done without doing a lot of work! 


Listing 1: 


ЖЖЖЖ / 
/* File: SinpleXCMD.c x/ 
*/ 


/* This is what a simple XCMD*/ 
/* written in Lightspeed °C’ */ 
/* In order to build this code */ 
/* resource, you will need the */ 
/* two files "HyperXCMD.h^ and */ 
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/* XCMDGlue.c. x / 
/* %/ 
Seay] 
/* To Build: x / 
[* */ 


/* СО Create a project using*/ 

/* this file as well as the */ 

/* XCMD.Glue.c file. (Set */ 

/* project tupe to XCMD (or */ 

/* XFCN) from the Project menu. */ 
x 


/* 

/* (2) Bring the project up to */ 
/* date. x/ 

/* */ 

/* (3) Build Code Resource. */ 
/* * 


/* (4) Use ResEdit to copy the */ 


/* resource to your stack.  */ 
/ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЕЖЖЖЖЖЖЖЖЖЖЖ / 


*include «MacTypes.h? 
8include «0SUtil.h» 

* include «MemoryMgr .h? 

* include <FileMgr .h> 

* include «ResourceMgr .h? 
*Üinclude “HyperXCmd.h” 


pascal void mainC paramPtr 2 
XCmdBlockPtr paramPtr; 


char theString(256]; /% A “Pascal” String */ 
theString[0) = “N0x0B ; /* Remember, static*/ 
theString[1] = 'H'; /* strings are placed*/ 
theString(2] = ʻE’; /* in the global pool*/ 
theString(3] = 'L'; /* CODE resources such */ 
theString(4] = ‘L’; /* as XCMDS and XFCNS*/ 
theString[5] = ‘0’; /* don’t have access to */ 
theString[6] = “ '; /* globals so uou have*/ 
theString[7] = ‘Ww’; /* to discretely set the*/ 
theString[8) = ‘0’; /* string’s value */ 
theString[9] = Ж” 

theString[10])= ‘L’; 


theStringl11]= ‘D’; 


/* A sample callback exemple */ 
paeremPtr-»returnValue = PasToZero( paramPtr, &theString 2; 


) 
Listing 2: 


[**X*XEXXEXEXXXEEEEXXEEXXEUXCXXEXXXEXXXXX/ 
/* File: HyperXCmd.h x/ 
MÀ 


/* Interface for standard d | 
/* HyperCard callback routines. */ 
[* */ 

/* Based on original work by  */ 
/* Dan Winkler of Apple Computer */ 
* x 


[BARRERA ХА ХХ ХХ АХА ХХХ ERA ХХХ ХХХ Ж / 


tupedef struct Str31 ( 
char data[32]; 
) Str31; 

typedef Str31 * Str3lPtr; 


tupedef struct XCmdBlock ( 
short paramCount; 
Handle params([16]; 
Handle returnValue; 
Boo leanpassF lag; 


void (*entruPoint)(); 
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short request; 
short result; 
long inArgs[81; 
long outArgs[4]; 
) XCmdBlock; 
typedef XCmdBlock *XCmdBlockPtr; 


/* Callback codes x / 


define xresSucc 0 
#def ine xresFail 1 
#def ine xresNotImp 2 


/* Callback request codes */ 
#def ine xreqSendCardMessage 1 
#def ine xreqEvalExpr 2 
#define xreqStringLength 3 
"define xreqStringMatch 4 


"define xreqZeroBytes 6 


"define xreqPasToZero 7 
#def ine xreqZeroToPas 8 
"define xreqStrToLong 9 
#def ine xreqStrToNum 10 
define xreqStrToBool 11 
"define xreqStrToExt 12 
"define xreqLongToStr 13 
"define xreqNumToStr 14 
#def ine xreqNumToHex 15 
define xreqBoolToStr 16 
define xreqExtToStr 17 


8define xreqGetGlobal 18 
define xreqSetGlobal 19 
"define xreqGetFieldByName 20 
"define xreqGetFieldByNum 21 
"define xreqGetFieldByID 22 
#def ine xreqSetF ieldByName 23 
8Sdefine xreqSetFieldByNum 24 
8define xreqSetFieldByID 25 
#def ine xreqStringEqual 26 
"define xreqReturnToPas 27 

#def ine xreqScanToReturn 28 
#def ine xreqScanToZero 39 


/* 
“Prototypes” for the Callbacks. Project 
must include XCmdGlue.c. 

*/ 


pascal voidSendCardMessage( ); 
pascal HandleEvalExpr(); 
pascal longStringLength(); 
pascal Ptr StringMatch(); 
pascal voidZeroBytes(); 
pascal Handle PasToZero( ); 
pascal voidZeroloPas(); 
pascal longStrToLong(); 
pascal longStrToNum(); 

pascal Boolean StrToBool(); 
pascal voidStrToExt(); 

pascal voidLonglostr(); 
pascal voidNumToStr(); 

pascal voidNumToHex(); 

pascal voidBoolToStr(); 
pascal void ExtTostr(); 
pascal Handle GetGlobal(); 
pascal voidSetGlobal(); 
pascal Handle GetF ieldByName(C); 
pascal Handle GetF ieldByNumC); 
pascal HandleGetF ieldByIDC); 
pascal voidSetF ieldByNameC ); 
pascal voidSetF ieldByNumC); 
pascal voidSetF ieldByIDC); 
pascal Boolean StringEqual(); 
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pascal voidReturnToPas(); 
pascal voidScanToReturn(); 
pascal voidScanToZeroC ); 


Listing 3: 


/^®%*ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖАЖЖЖАЖЖЖЖЖЖЖЖЖ / 

/* File: XCMDGlue.c ж/ 

/* x/ 

/* Callback routines for XCMDs %/ 

/* and XFCNs. This file should*/ 

/* be included in your project — */ 
*/ 


/* Based on original work bu */ 
/* Dan Winkler of Apple Computer */ 
х/ 


/ХХХХХХА ХХХ ХА ХХХХХА ХА ХХ ХХХ АХУ / 


®include «MacTypes.h? 
#include ‹050+11.№ 
include <MemoryMgr .h> 
include «FileMgr.h» 
include «ResourceMgr .h> 
* include “HyperXCmd.h” 
®include <math.h> 


pascal void SendCardMessage(paramP tr, msg) 
XCmdBlockPtr paramPtr; 
StringPtr msg; 
/ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
* Send а message back to 
* hypercard. The input message 
* is a Pascal String 
XXXXXXXXXXXXXXXXXXKXXKK/ 
( 
paramPtr-)inArgs[0] = (long)msg; 
paramPtr-»request = xreqSendCardMessage; 
Са11Равса1( paramPtr->entryPoint 2; 


pascal Handle EvalExpr(paramP tr , expr ) 
XCmdBlockPtr paramPtr; 
Str ingPtr expr; 

[***XXxXxxxxxxxxxxxxxxxxxx 

x Evaluate a Hypertalk expression 

* returning the result as a "C" 

* string 

ХХХХХХХХХХХХХХХХХ ХХХ ХХХ / 


paramPtr-> inArgs(@] = (long)expr; 

paramP tr->request = xreqEvalExpr; 
CallPascalC paramPtr->entryPoint ); 

return (Handle )paramPtr-> outArgs (01; 


pascal long StringLength(paramPtr,strPtr) 
XCmdBlockPtr paramPtr; 
Str ingPtr strPtr; 

/ХАХХХХАХ ХХХ ХХХ ХХХ ХХХ 

* Counts the number of 

* characters in the input 

* string from StrPtr to end 

* of string (zero bute) 

XXXXEDOOOODOOOOOOOOOE XXX / 

( 
рагатРіг-› inArgs[@] = Clong)strPtr; 
paramPtr->request = xreqStringLength; 

CallPascalC paramPtr->entryPoint 2; 

return Clong)paramPtr->outArgs [9]; 


pascal Ptr StringMatch(paramPtr, pattern, target) 


XCmdBlockPtr paramPtr; 
StringPtr pattern; 
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Ptr target; 

/EKYXXXXXXXXXIXXXIXXXKXKXE 
Case-insensitive match 
for pattern anuwhere in 
target, 


x 
x 
x 
x 
* Returns a pointer to first 

* character of the first match, 

* in target or NIL if no match 

* found. pattern is a Pascal string, 
x 
x 
( 


and target is a zero-terminated string. 
жж у 


paramPtr-,inArgs[0] = Clong)pattern; 
paramPtr-,)inArgs[1]) = Clong)target; 
paramPtr->request = xreqStringMatch; 
CallPascal( paramPtr->entryPoint ); 
return (Ptr paramPtr->outArgs [8]; 


) 


pascal void ZeroButes(paramPtr,dstPtr,longCount) 


XCmdBlockPtr paramPtr; 
Ptr dstPtr; 
long longCount; 
[/** xxx ХХХ ххх Ж 
* Clear memory starting at destPtr 


ж through destPtr+longCount 
MYCOCOOOOOECEXOOOECEE E XX XXX / 


( 
paramPtr-> inArgs(@] = Clong)dstPtr; 
paramPtr-> inArgs[1] = longCount; 
paramPtr-»request = xreqZeroBytes; 
CallPascal( paramPtr->entryPoint ); 


pascal Handle PasToZero(paramPtr, pasStr 2 
XCmdBlockPtr paramPtr ; 
StringPtr passtr; 
ЖЖЖЖ 
х Convert a Pascal string (578255) 
х {о а zero-terminated string. 
* Returns а handle to а zero-terminated 
* string. The caller must dispose the handle. 
x 
x 
x 


Useful for setting the result or 
an argument you send from 
* an XCMD to HyperTalk. 
KXXEXXEXXXXrkirtixirrxkr/ 
( 
paramPtr-> inArgs(@] = Clong)pasStr; 
peramPtr-»request = xreqPasToZero; 
CallPascalC paramPtr-rentryPoint ); 
return (Handle )paramP tr-> outArgs [0]; 


pascal void ZeroToPas(paramPtr,zeroStr,pasStr) 
XCmdBlockPtr paramPtr; 
char *zeroStr; 
Str ingPtr passtr; 
[**X*X*xxxxxXxxxxxxxxxxxxxx 
Copy the zero-terminated 
string into the Pascal String. 


x 
Ж 
x 
* You create the Pascal string 
* and pass it by reference. 
x 
xx 
( 


XXXXXXXXXXXXXXXXXXXxx/ 
рагатРіг-› іпАгдѕ(01 = Clong)zeroStr; 
рагатРіг-› іпАгдѕ (11 = Clong)pasStr; 


paramPtr->request = xreqZeroToPes; 
Са11Разса1( paramPtr->entryPoint ); 
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pascal long StrToLong(paramPtr,strPtr) 
XCmdBlockPtr paramPtr; 
Str31 *strPtr; 

Ы 5222222522222222454: 

% Convert а string of ASCII 

* characters to an unsigned 

* long integer. 

KXXXXXXECEEEOOOEEX XXX / 

( 
paeremPtr-»inArgs[0] = Clong)strPtr; 
paramPtr->request = xreqStrToLong; 

CallPascalC paramPtr-»entryPoint ); 

return Clong)paramPtr->outArgs(8); 


pascal long StrToNum(paramPtr, str) 
XCmdBlockPtr paramPtr; 
Str31 *str; 

/****XXXXxXxxXkkxxxxkxxx 

* Convert a string of ASCII 

* characters to a signed 

* long integer. 

XXXXXXXXXX*tX*xxtkxxrkkx/ 

( 
peramPtr-?inArgs[0] = Clong)str; 
paramPtr-,jrequest = xreqStrToNum; 

CallPascal( paramPtr->entryPoint ); 

return peramPtr-»outArgs(0]; 


pascal Boolean StrToBool(paramPtr,str) 
XCmdBlockPtr paramPtr; 
Str31 *str; 


2 
/®*ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


* Convert the Pascal strings 


x ‘true’ and ‘false’ to booleans. 
YXXXXEXEYXXXXXEXEXEEXXEX/ 


( 
peremPtr-?inArgs[8] = Clong)str; 
paramPtr-»request = xreqStrToBool; 
CallPascalC paramPtr->entryPoint ); 
return (Boolean )paramPtr->outArgs(8); 


pascal void StrToExt(paramPtr, str, myext) 
XCmdBlockPtr paramPtr; 
Str31 *str; 
long *nyext; 
[****XXxxtXxtxktztxxkt1xxxt 
* Convert a string of ASCII digits 
* to an extended long integer. 
x 


* The return value is passed 
* by reference and you must 
* asllocate the space before 


* calling this routine. 
XXXXXXXXEXXXXXXXXXXxxxxx/ 


( 
paramPtr-jinArgs[@0] = Clong)str; 
paramPtr-> inArgs[1] = Clong)myext; 
peramPtr-'request = xreqStrToExt; 
CallPascalC paramPtr-»entryPoint ); 


pascal void LongToStr(paramPtr ,posNum, mystr ) 


XCmdBlockPtr paramPtr; 

long posNum; 

Str31 *mystr; 
[/***XXXXXXXXXxXxxxxxtxxxxx 
* Convert an unsigned long integer 
* to a pascal string representation 
* Useful for sending numbers back 
* to Hypercard. 
x 
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* You create mustr and pass 

* it by reference. 

XXOOOOOOOOOOGECEXOECEEE XE XXX / 

( 
paramPtr-> inArgs[@] = Clong)posNum; 
paramPtr-> inArgs[1] = Clong)mystr; 
paramPtr-?request = xreqLongToStr; 

CallPascalC paramPtr-»entrgPoint 2); 


pascal void NumToStr(paramPtr,num,mystr) 
XCmdBlockPtr рагатР{г; 
long num; 
Str31 *mustr; 
/^®^*Ж*ЖЖЖЖЖЖЖЖХЖХЖЖАХЖЖЖЖЖЖЖ 
Convert а signed long integer 
to a pascal string representation 
Useful for sending numbers back 
to Hupercard. 


You create mustr and pass 


it by reference. 
XXXXEXXXXXXXXXXXxxxxxxx/ 


em € X MH HH 3% 3X м 


paramPtr-»inArgs[0] = num; 

paramPtr-»inArgs[1] = Clong)mystr; 

peramPtr-»request = xreqNumToStr; 
CallPascalC paramPtr-?entryPoint 2); 


pascal void NumToHexCparamPtr,num,nDigits,mystr?) 


XCmdBlockPtr paramPtr; 


long num; 
short nDigits; 
Str31 *mustr; 


/YFXEXTKKXKXXXXXXX1X1XXXKKKKK 


Convert an unsigned long integer 
to a hexadecimal number and put it 
into a Pascal string. 


by reference. 


x 
x 
x 
Ж 
* Тһе “output? string is passed 
x 
XOOOOOOOOOOOOOOGOOOEXXC / 

( 


рагатРіг-› іпАгдѕ (0) = num; 
paramPtr->inArgs[1] = nDigits; 
рагатРіг-› inArgs[2] = (long)mustr; 


paramPtr->request = xreqNumToHex; 
CallPascalC paramPtr->entryPoint ); 


pascal void BoolToStr(paramPtr,bool,mystr) 
XCmdBlockPtr paramPtr; 
Boolean bool; 
Str31 *mystr; 
/^Ж*ЖЖЖЖЖЖХЖЖЖЖЖЖАЖЖАЖЖЖХЖЖЖ 
* Convert a boolean to 
* ‘true’ or ‘false’. 
x 
* The “output” string is passed 
* by reference. 
XXXXXXXXXXXXXXXXXXKKXXKXK/ 


рагатРіг-» inArgs[@] = (long)bool; 

peremPtr-?inArgs[1] = Clong)mystr; 

peramPtr-»request = xreqBoolToStr; 
CallPascal( paramPtr-»entrygPoint ); 


pascal void ExtToStr( paramPtr, myext, mystr) 
XCmdBlockPtr paramPtr ; 
char *myext; 
Str31 *mystr; 

/ХҰХХХАХАХАХ АА ХА ХХХ ХХХ ХХХ 
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* Convert an extended long 

* to its string representation 

* 

* The “output?” string is passed 

* bu reference. 

ХХХХХХХХХХХХ ХХХ ХХХ ХХХ / 

( 
paramPtr-> іпАгдѕ 0] = (long)muext; 
paramPtr-> inArgs(1] = Clong)mystr; 
peramPtr-»request = xreqExtToStr; 

CallPascalC paramPtr-»entryPoint 2; 


pascal Handle GetGlobal(paramP tr ,globName ) 
XCmdBlockPtr paramPtr; 
StringPtr globName; 

/YYXXXXXXXKXXXXXKXXKXKKXXKEA 

* Return a handle to a zero-terminated 

* string containing the value of 

* the specified HyperTalk global variable. 

ЖЖЖЖЖААЖЖЖЖАЖЖАЖЖЖЖЖЖЖЖЖЖ / 

( 
рагатРіг-» іпАгдѕ[0) = Clong)globName; 
paramPtr->request = xreqGetGlobal; 

CallPascalC paramPtr-»entryPoint ); 

return CHandle)paramPtr->outArgs (01; 


pascal void SetGlobal(paramP tr, globName,globValue) 
XCmdBlockPtr paramPtr; 
StringPtr globName ; 
Handle globValue; 

Ы, 52.5 222222224222. 

Set the value of the specified 

Huperlalk global variable to be 

the zero-terminated string in globValue. 

The contents of globValue 

are copied, uou dispose the 


handle 
XXXOOOOOOOOOOOEOEOEGEOX XE / 


m~ % 3€ X з % % X 


paramPtr-?inArgs[0] = Clong2globName; 

paramPtr-»inArgs[1] = Clong)globValue; 

peramPtr-?request = xreqSetGlobal; 
CallPascalC paramPtr-?entryPoint ); 


pascal Handle GetFieldByNameCparamPtr , cardF ieldF lag, fieldName) 


XCmdBlockPtr paramPtr; 
Boolean cardF ieldF lag; 
StringPtr f ieldName; 
[**X**xx xxx xxx xxxv ERE REESE 
Return a handle to a zero-terminated 
string containing the value of 
field fieldName on the current 
card. You must dispose the handle. 


you want the contents of a card 
field or to false if you want 
the contents of a bkgnd field 


x 
x 
x 
x 
x 
* Set cardfieldFlag to ture if 
x 
x 
x 
ЖЖАХЖЖЖЖЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖХ / 
( 
paramPtr-> іпАгдѕ (0 ] = Clong2cardF ieldF lag; 
paramPtr-»inArgs[1] = Clong)2fieldName; 
peramPtr-?request = xreqGetF ieldByName; 
CallPascalC paramPtr-?entryPoint 2; 
return (Handle )paramPtr-) outArgs [8]; 


pascal Handle GetF ieldByNumCparamP tr, cardFieldF lag, f ieldNum) 


XCmdBlockPtr paramPtr; 
Boolean cardFieldF lag; 
short f ieldNum; 


/ *X*Xxooooooeecoooexx 


* Returns a copy of the contents of the field whose number is 


* fieldnum on the current card. 


* You dispose the handle when you are done. 
ЖЖЖЖЖЖЖЖЖАЖЖАЖАЖЖЖЖЖЖЖЖЖЖХ / 


( 
peramPtr-?inArgs[0] = Clong)cardFieldF lag; 
peramPtr-?inArgs[1] = fieldNum; 
paramPtr->request = xreqGetF ieldByNum; 
CallPescalC paramPtr->entryPoint ); 
return CHandle)paramPtr-> outArgs 101; 


) 


pascal Handle GetFieldByID(paramPtr,cardF ieldF lag, fieldID) 
XCmdBlockPtr paramPtr; 
Boolean cardF ieldF lag; 
shor t f ieldID; 
[F*XXXXOOOOOGOGECECEG GEEK 
* Returns a copy of the contents of the field whose id is 
* fieldID on the current card. 


* You dispose the handle when you are done. 
XXOOOOOOCEECECEEEX X EE XX XXX / 


( 
peramPtr-?inArgs[20] = Clong)cardF ieldF lag; 
paramPtr-) inArgs(1] = fieldID; 
peremPtr-?request = xreqGetF ieldByID; 
CallPascalC paramPtr- entryPoint ); 
return CHandle)paramPtr-»outArgs(0]; 


) 


pascal void 
SetF ieldByNameCparamP tr , cardF ieldFlag,f ieldName,f ieldVa1) 
XCndBlockPtr paramPtr; 
Boolean cardFieldF lag; 
StringPtr fieldName; 
Handle fieldVal; 
/***xxxx xxx x xxx xxxxxxxx 
* Set the value of the field whose name is fieldName on 
* the current cerd. 
* You dispose the handle when you are done. 
XXOOOOOOOOECIOOOGOEOECEEXEEXX / 


( 


рагатРіг-› іпАгдѕ 0] = Clong)cardF ieldF lag; 
paramPtr-»inArgs[1] = Clong)f ieldName; 
рагатРіг-> inArgs(2] = Clong)f ieldVal; 


paramP tr->request = xreqSetF ieldByName; 
) CallPascal( paramPtr-»entryPoint ); 


pascal void 
SetF ieldByNumCparamPtr , cardF ieldF lag, f ieldNum, f ie1dVa1) 
XCmdBlockPtr paramPtr ; 
Boolean cardF ieldF lag; 
short f ieldNum; 
Handle f ieldVal; 
[3*XXXXXXXOCOOCEOECEE X XX X 
* Set the value of the field whose number is fieldnum on 
* the current card. 


* You dispose the handle when you are done. 
XOOODOOODOOOCEOEEXCEX XXX / 


( 
peramPtr-?inArgs[0] = Clong2cardFieldF lag; 
peremPtr-?inArgs[1] = fieldNum; 
peramPtr-»inArgs[2] = Clong)f ieldVal; 
peremPtr-»request = xreqSetF ieldByNum; 
CallPascal( paramPtr->»entryPoint ); 


pascal void 
SetF ieldByIDCparamP tr, cardF ieldFlag,f ieldID,f ieldVal) 
XCmdBlockPtr paremPtr; 
Boolean cardF ieldF lag; 
short f ieldID; 
Handle f ieldVal; 
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[**xeeooooeocoooeeeeex 


* Set the value of the field whose id is fieldID on 
* the current card. 
* You dispose the handle when 


* you are done. 
XXX XXX X XXxx kc KEKE RENE / 


( 
peremPtr-?inArgs[Q0] = Clong)cardFieldF lag; 
paramPtr-> inArgs(1] = fieldID; 
peremPtr-»inArgs[2] = Clong)f ieldVal; 
peramPtr-»request = xreqSetFieldByID; 
CallPascalC paraemPtr— entrygPoint ); 


pascal Boolean StringEqual(CparamPtr,str 1,str2) 
XCmdBlockPtr paramPtr; 
Str31 *str 1; 
Str31 *str2; 

[****Xxx xxxxxxxxxxxxxxxx 

* Returns true if the strings match, false otherwise. 


* Compare is case insensitive 
XXXXXXXXXXXX XXXXXXXXXxx/ 


( 
рагатРіг-› іпАгдѕ (01 = Clong)str 1; 
paeramPtr-»inArgs[1] = Clong)str2; 
peramPtr-?request = xreqStringEqual; 
Са11Раѕса1( paramPtr-»entryPoint ); 
return (Boolean)paramPtr-?outArgs(2]; 


pascal void ReturnToPas(paramPtr, zeroStr, pasStr) 
XCmdBlockPtr paramPtr; 
Ptr zerostr; 
StringPtr pasStr; 
/XEKKXXXXXXXXXXXXXXXXXXXX 
* Collect characters from zeroStr 
* to the next carriage Return and return 
* them in the Pascal string pasStr. 
* If no Return found, collect chars 
* until the end of the string (zero) 
YXCOODOCECECECOEOOECEEECEEX XXX / 
( 
paramPtr-> inArgs[@] = ClongOzeroStr; 
peramPtr-»inArgs[1] = Clong)pasStr; 
peremPtr-?request = xreqReturnToPas; 
Са11Раѕса1( paramPtr->entryPoint ); 


pascal void ScanToReturn(paramP tr, scanHnd] ) 
XCmdBlockPtr paramPtr; 
Ptr *scanHnd] ; 

[**XXXXXXXxxxxxxxxxxxxxx 

* Position the pointer, scanPtr,at a Return character 


* or а zero byte. 
XXXXXXXXEXXXXXXXXEXXXxXx/ 


( 
peremPtr-»inArgs[20)] = (long)scanHnd1; 
paramPtr->request = xreqScanToReturn; 
CallPascal( paramPtr->entryPoint ); 


pascal void ScanToZero(paramPtr, scantnd1) 
XCmdBlockPtr paramPtr; 
Ptr *scanHndl; 

/ Xxx xx XXe ХХХ ХХХ ХХ 

* Position the pointer, scanPtr, 


х at a zero byte. 
XXXXXXXXXXXXXXXXXXXXXXx/ 


( 
peramPtr-»inArgs[0] = Clong)scanHnd] ; 
paramP tr->request = xreqScanToZero; 
CallPascal( paramPtr->entryPoint ); 
) 
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XCMD Corner: XCMD Libraries 


Modularity and Coupling 

As you to explore XCMDs, you should continue to discover 
new and interesting properties of these routines. Two properties 
are particularly noteworthy because they lead to code that is 
usable outside of Hypercard. They are strong modularity and 
weak coupling. 

You determine the modularity of a routine by counting the 
number of tasks it performs. Strongly modular routines handle 
one task. If you were writing a spreadsheet program, you would 
most likely separate the routine that calculates the value of a cell 
from the routine that displays that value. Combining these 
functions results in weak modularity. Weakly modular code is 
hard to debug because you can easily lose track of what the 
routine is doing at a given point. 

Coupling describes how the program interacts with the 
outside world. Weakly coupled routines operate only on data 
passed as formal parameters. Weak coupling eliminates harmful 
side-effects caused by relying on global memory. Weakly 
coupled programs force you to think over how and when to pass 
data back and forth. 

Well written XCMDs exhibit both strong modularity and 
weak coupling. Most XCMDs perform one task (strongly 
modular XCMDs), typically to add a missing feature to Hyper- 
talk. XCMDs interface to Hypertalk using a very strict protocol, 
passing parameters via the command block record. This protocol 
coerces weakly coupling in your code. 


Software Breadboard 

Strong modularity and weak coupling suggest that you can 
create libraries of useful routines for use both in Hypercard and 
in programs of your own design. Think of Hypercard as a 
“Software Breadboard”, a test platform that you plug code into 
for checkout and debugging. Once working, the routine can be 
dropped into any application. 

An example ofa set of routines that play well in this scenario 
are the calls to the File Manager. Every (non-trivial) application 
needs to call on the file manager to opena file, access information 
in the file and then close it. I decided to build my case around 
accessing a file because Hypercard itself doesn’t handle files 
“according to Hoyle”. Hypercard violates two precepts of the 
user interface guidelines when opening a file: (1) The user is 
required to know the full pathname of a file if it is not in the 
current working directory and (2) the OpenFile command per- 
forms an unexpected action; if it cannot find the file, it creates it! 

In order to properly open a file, you first present the user with 
a dialog that contains the list of files in the current working 
directory. This dialog allows the user to flip from drive to drive 
as well as change directories. The standard file package provides 
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you with the “vanilla” get file dialog. When the user selects a file 
and clicks the “Open” button, your code queries the reply record 
to discover the file’s name, working directory id and file type. 

The working directory id pinpoints which folder contains 
the document. If you made a killing on Macintosh software and 
have been away on some deserted island for the past several 
years, the working directory assumes the role traditionally held 
by the volume reference number. 

Given the file name and working directory, you can recon- 
struct and return the full pathname to Hypercard so that it can be 
used by Hypercard’s “open” command (pathname reconstruc- 
tion is the subject of a future article). However, it’s just as easy 
to open the file ourselves to ensure that it opens in whatever 
manner is expected on the Macintosh. The XCMD that opens the 
file is left as an exercise. 


GetFileName XFCN 

The XFCN, GetFileName (Listing 1), displays strong 
modularity - its sole task is to get the name of a file from the user. 
By relying only on data passed to it formally, it also demonstrates 
weak coupling. This XFCN provides a general purpose tech- 
nique for getting the name of a file from the user. GetFileName 
calls on a routine Called GetFileNametoLoad in HyperUtils.c 
(listing 2). The prototypes for HyperUtils are found in 
HyperUtils.h (listing 3). HyperUtils contains a set of re-usable 
utilities that do not presume the existence of Hypertalk. These 
routines aren't encumbered with the XCmdBIkPtr interface. 

GetFileNameToLoad accepts as its inputs a list of file types 
(up to 4) to filter out in the open dialog. If you were writing a text 
import routine, you might want to present the user with only files 
of type ‘TEXT’. From Hypercard, you would then invoke 
GetFileName as: 


Put GetFileNameC “TEXT” / into it; IF it is not 
empty then - User selected a file put item 1 of it 


into FileName put item 2 of it into FolderID 
end if 


With little effort, we’ ve created a re-usable, general purpose 
XCMD. Pass the name and the FolderID to any File Manager call 
that requires the file's name and volume reference number (aka 
working directory id). I will call upon this XCMD in future 
editions of this column so you'll have ample opportunity to see 
it action. 

An obvious addition to this list an xcmd that asks the user for 
the name of a file to save by calling SFPutFile. This is a simple 
modification to GetFileNameToLoad so I'll leave it as yet 
another exercise. 

After creating enough XCMDs, you'll soon view them as 
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general purpose routines with a specific interface (XCmdBlkPtr) 
to HyperTalk. With this in mind, you should have no trouble 
creating XCMD libraries that can be used in other applications. 
Get in the habit of separating the Hypertalk interface, including 
any callbacks, from the action code. The XCMD itself then 
becomes an interface between HyperTalk and your code. 


Listing 1: GetFileNane.c 


/¥ERRERERERERERA REAR AAA REAR ERY / 


/* File: GetFileName.c *] 

/* */ 

/* Using Standard File Package */ 

/* queru the user for the name */ 

/* of a file to open, and return*/ 

/* the name along with the */ 

/* working directory id of the */ 

/* file. х/ 

/* Paramters: х/ 

/* paramCnt = number of types*/ 

/* params(0..3] = the types to */ 

/* filter for Csee Inside Mac. */ 

/* 1-523 for details "7 

ji ——.= 

/* To Build: х/ 

/* (1) Create а project using*/ 

/* this file as well as the */ 

/* XCMD.Glue.c file. (Set x/ 

/* project type to  XCMD Cor */ 

/* XFCN) from the Project menu. */ 
x 


/ 
/* (2) Bring the project up to */ 
/* date. * 

/* (3) Build Code Resource. */ 
/* (4) Use ResEdit to copy the */ 


/* resource to your stack.  */ 
ЫЫ SEAR ER ERE EAA EA ER EX / 


include «MacTypes.h? 
include «0SUtil.h» 
include <MemoryMgr .h? 
include «FileMgr.h? 
“include «ResourceMgr .h? 
include ‹раѕса1.ћ 
include «strings.h? 
include *HyperXCmd h^ 
include *"HyperUtils.h^ 


pascal void main( paremPtr ) 
XCmdBlockPtr paremPtr; 


( 
short FileWDID; 
short numTypes; 
short i; 


SFTypeList typs; 
cher  FileName[256]; 
cher — WDIDString(321]; 
char comma(2]; 


ifC !paramPtr->paramCount 2 
e Mes = -]; /* select all since no type specified */ 
else 
numTypes = paramPtr-?paramCount; 
for( i = 0; i < numTypes; i++ ) 
BlockMove( *(paramPtr-»params[i]), &typs(il, 4L ); 


*FileNeme = 40”; 


іҒС GetFileNameToOpen( typs, numTypes, FileName, &FileWDID ) 
)( 
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NumToStr( paramPtr, Clong)FileWDID, &WDIDString ); 
PtoCstr( WDIDString ); 


comma[0] 
commal 1] 


‘i’;  [* for you MPW folk */ 
“4” 


strcat( FileName, сотта ); 
strcat( FileName, WDIDString 2; 
CtoPstr( FileName ); 


paramPtr-»returnValue = PasToZero( paramPtr, FileName ); 


Listing 2: HyperUtils.c 


7Ь5552225522222222222222222557/ 


/* HyperUtils.c */ 
/* A collection of useful */ 
/* routines... */ 


/®*ЖЖЖЖЖЖЖЖЖХЖЖАЖХЖЖЖХЖЖЖЖЖЖЖ / 
tinclude «МасТурев.һ» 


#inc lude 
include 
include 
include 
include 
include 
include 


«0SUtil.h» 
«MemoryMgr . h? 
«FileMgr.h? 
«ResourceMgr .h> 
«StdF ilePkg.h»? 
*HyperXCmd .h^ 
*HyperUt ils.h^ 


void CenterWindowC wptr ) 

WindowPtr  wptr; 
[ X XXoXXceocoIcIOIOOOIOOIOOOIC ХА ХХ 
Center a window in the current 
Screen port. Note: Does not 
attempt to work with multi-screen 
systems. 


This code is inspired by a 
similar routine written by Steve 
Maller in MPW Pascal. Thanks Steve. 


XXXXXFXFXXXXXXXKXXXXXXXXXXXKXK / 


е % »* »* з зе * ж 


short hWindSize = wptr- portRect.right - wptr->portRect. left; 
short vWindSize = wptr— portRect.bottom - wptr->portRect.top; 
short hSize = wptr->portBits.bounds.right - wptr- 
»portBits.bounds. left; 

short vSize = wotr-»portBits.bounds bottom - wptr- 

»por tBits.bounds. top; 


MoveWindowC wptr, 

( hSize - hWindSize ) / 2, 

( vSize - vWindSize * 20) / 2, 
false 

); 
) 


void ConcatC stri, str2 ) 

char *str 1; 

char *str2; 
[ 3X XXXOOOOOOOOOOOOOOOOOOOOEOOROENE 
Append string 2 to the end of 
string 1. Both strings ere 
pascal-format strings. 


stri must be large enough to hold 
the new string and is essumed to 
be of Type Str255 (a pascal string) 


XXXXXXXxXxXxxxtrtxx x xxxxrxxxxxkkxx/ 


m % 0 »* »* »* М м М 


short Теп! = *stri; /***number of chars in str 1***/ 
short len2 = *str2**;/***number of chars in str 2***/ 
cher *temp; /*** string pointer — ***/ 


ісігі += len2 + 1;/*** add sizes to get new size***/ 


@ The Best of MacTutor, Vol. 5 


temp = str1 + leni + 1;/*** move to end of str 1***/ prompt(@] = 40” 
whileC len2 ){ 
¥tempt+ = *str2++; /*** add char to temp & move***/ /*** Get and put up the standard file ***/ 
—len2; /*** until 811 characters are added***/ /*** dialog. You will only see the file***/ 
/*** types that you filtered for. If ***/ 
/*** you filtered for no files, then ***/ 


) /*** all files will display xxx / 

void CopyPStrC pStr1, pStr2 ) GetPort( &oldPort ); 
char *pStr1; dlogID = GetNewDialogC Cshort2getDlgID, (Ptr NIL, 
char *pStr2; (Ptr UPFRONT ); 

/YYXXXXX1XXXKXXKXXXKXKEXXXXXKEXX 

* Copu the contents of pstr1 into SetPort( dlogID ); 

* pstr2. The strings are assumed CenterWindow( dlogID ); 

* to be of type STR255 (length byte where.h = dlogID->portRect. left; 

* precedes data where.v = dlogID->portRect. top; 

x 


LocalToGlobalC &where ); 
Xoooooceoeeooooooee eoe / 


{ short i; SFGetFileC where, prompt, (Ptr NIL, typCnt, typs, (Ptr NIL, 
char *tstr; &reply ); 
tstr = pStr2; DisposDialog( dlogID ); 


SetPort( oldPort ); 
for( i = 0; i <= *pStri; 1++ ) 
*tstr** = *pStr ltt; /*** [f the user selected a file, let’s ***/ 
/*** get the information about it ***/ 


short GetFileNemeToOpen(C typs, typCnt,theName, theWDID ) if (replu.good)( 
SFTypeList typs; *theWDID = reply.vRefNum; 
short typCnt; PtoCstrC (char *D&reply.fName ); 
char *theName; strcpyC theName, &reply.fName ); 
short *theWDID; ) 

/®*^ХЖЖЖЖЖЖЖЖЖХАЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖ return( replu.good ); 

* Invokes SFOpenFile to queru the ) 

* user for the name of a file to 

: open. Listing 3: HyperUtils.H 

* In: List of types of files to / XXX xxxcoooeoooceoocceeceeoee EE / 

* filter for Cup to 4) /* HyperUtils.H x/ 

* Out: fileName if picked in theName /* Header file for HyperUtils.c*/ 

* working directory in theWDID /* routines... х / 

* nil otherwise ХХХ EKER RES ERE ХХХ КЖК / 

* the file’s volum ref num. 

* ( Note that the space for the #def ine NIL ØL 

* string must be allocated by the def ine UPFRONT -1L 

* caller). 

ЖЖЖЖ / voidCenterWindow( WindowPtr wptr ); 

{ voidConcat( char * stri, char * str2 ); 
Point where; void CopyPStr¢ char * pStr1, char * pStr2 ); 
char = prompt(1]; short GetFileNameToOpen(SFTypeList typs,short typcnt, char 
SFReply reply; *theName, short *theWDID); = 
GrafPort *oldPort; Se} 
WindowPtr (10410; SEEPS 
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HyperChat™ 
HyperArrays 


on HyperChat 


HyperMedicine: 
Using Hypercard to Solve Problems 

This month we will look at ways people have solved prob- 
lems in the medical field (my origin) using Hypercard. One of the 
reasons Hypercard is so popular in the medical field is that after 
spending so many years learning to be a doctor people feel that 
investing more to be a computer programmer is not justified. 
There is very much a “We want solutions now!” mentality. 

The first problem was how do you get the patient more 
involved in his/her case decision making process without tying 
up too much of your surgeon’s time? Harold Lyon from Dart- 
mouth Medical School used Hypercard and a laserdisc to form an 
interactive decision making tool. The topic is “Prostatectomy or 
Watchful Waiting”. The disc shows the risks and rewards of 
having the operation. Patients are interviewed and even doctors 
that have been patients. It gives you all the pros and cons of 
having the operation. The other purpose of the laserdisc is to 
gather data about patients and follow up treatments. This pro- 
gram that they have created has legal, ethical, educational, and 
research implications. It also protects the doctor by documenting 
the patients informed consent. 

Harold Lyon gives some useful tips in preparing a vide- 
odisc> 

- Always put SMPTE on the source tape. 

- Flowchart the disc 

- Use the same microphones at the same distance to maintain 
sound quality 

- Train the speakers not to speak at the same time 

- Work with one studio and film group 

- Use small organized teams 

- Never try to insert single words in audio 

- Reach final script consensus prior to off-line edit 

- Use colorbars on original source tapes 

- Keep good track of script versions for team 

- Plan the important details first 

- Prepare more before on-line edit 

- The video editor must be part of the team not someone hired 
for piecemeal work 

- Consider carefully the use of one versus two camera shoots 

- Ask interviewee the questions on video. Tape record these 
questions, play them back, and write them down. Take some head 
shots for cutaways. Then take the interviewer asking the same 
questions with a delay between each. Also take shots of inter- 
viewer sitting quietly for cutaways. 

- Allow some spontinaity on line 

- Film making and videodisc film making require different 
skills- be careful who you hire. 

- Evaluate the disc before it is pressed changes are hard to 
make after pressing 

- MacRecorder from Farralon was invaluable 

- Consult experts 
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- Study other potential markets for your videodisc before 
shooting. With minor additions different applications can be 
made. 

These tips are typical of the type of problems you will 
encounter when you make a videodisc. 

The second interesting application is an article on XCMD's 
written By Scott Vore MD. He is an anesthesiologist who wanted 
to track patients blood pressure, heart rate, drugs administered 
etc. He decided to do it in Hypercard however he found that he 
had to keep track of an array of data. So he wrote an XCMD called 
Hyperarray to do just that. 

If you hear of any interesting applications Hypercard has 
been put to send them to us. 

Send articles ideas, comments etc to Applelink: STAUDER 


end HyperChat 


HYPER ARRAYS 

[Scott's background is entirely self taught but he has been at 
it for 3 plus years now] 

First of all, before you read any further I feel compelled to 
make the following disclaimers: 

I am not, never have been, never plan to be a ‘real’ program- 
mer. I'm totally self taught, thanks in most part to a handful of 
books and one excellent journal (we know which one)-conse- 
quently my programming ‘style’, if ‘style’ can describe it, 
contains bits and pieces of code examples I’ve seen elsewhere 
and often; in my haste to get things to work, I'll leave in bits and 
pieces of code that serve no real purpose but should be removed 
if programming correctness were to be maintained. I'm sorry if 
this has happened here- with more time I could make it all prettier 
but I hope I’ ve given someone enough to work with that they too 
can write and make things neat. My only motivation has been to 
make this machine work for me ,(with no formal training I have 
never felt competent to try and teach others). In that process, 
however I have learned a few things and some of those things 
seem important ( I guess I'll let the editors decide just how 
important). Oh well, on with the show... 

In my programming experience with Hypercard, I have 
never ceased to be amazed at the power , elegance, and simplicity 
inherent in this product. Every now and again, however, we all 
run up against 'the wall' and are forced to either change our 
approach or find another method to solving a particular problem. 

Currently I am writing a stack that will be used in an 
Operating Room environment to allow an Anesthesiologist to 
record various pieces of dataat specific time intervals throughout 
acase. Typically, the blood pressure, heart rate, and various other 
measurements are kept track of throughout a case so that the 
Anesthesiologist can keep track of the trend in these parameters 
as time passes, additional drugs are administered, and as the 
surgery progresses. 

My particular problem was in storing the information in a 
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way that was accessible in arandom fashion, retrievable between 
calls to different stacks and between calls to shutdown that stack. 
In other words I wanted a data structure that was ‘global’ in nature 
and that acted as an array. 

Being a faithful MacTutor reader I am aware that we are 
being admonished to always try and solve our problems in 
Hypertalk before resorting to writing an XCMD, so in all fairness 
I must say that the XCMD described below does have a Hypertalk 
counterpart although somewhat more cumbersome. The ex- 
ample stack I have enclosed will compare the two methods. 

Ok, enough of all this, what is my problem? 

I wanted to create an array that was accessible throughout 
Hypercard. Fine. How? One method is to create a field some- 
where in my stack that has each line representing a different time 
point and each item on that line representing a different array 
variable. 

e.g. put 10 into line 10 of cd fld “array” 

While this approach does serve its purpose well a multi- 
dimensional array must rely on scripting to enter the various data 
points with commas interspersed between items and those same 
commas must be stripped off as the data is retrievable- doable but 
messy. 

My approach was to create a one dimensional array (though 
a multidimensional array can easily be created) as a resource, 
attach that resource to the stack in question and access that array 
with calls to an XCMD. The array is very quickly accessed, is 
‘global’ in nature and can be accessed easily through Hypercard. 

The first step consists in determining the size of the array. 
For the example stack I have created a 60 element array since in 
a time based environment 60 works out well. Now, the array 
Resource must be created. There are two options here- the 
resource can be created from the program (from the XCMD) or 
it can be created with Rmaker and pasted into the stack in 
question. I chose the latter approach ( to me, it was the easiest 
way). 

At this point decide on a Resource type too. 

I chose ANES for the simple reason that I am an anesthesi- 
ologist . 

The Rmaker source code is as follows: 


ANESTH.RSRC 
type ANES = GNRL 
1005 


д 
.H 

0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 


0000 0000 0000 0000 
This, obviously initializes the values to zero and sets the 
values in hexadecimal format though integer or any other 
Rmaker legal format could have been used. If the hex format is 
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maintained and you want to store character values then be sure 
and use some variation of the numtostring function to convert the 
character to its ASCI value and the reciprocal function to convert 
it back on retrieval. 

After running Rmaker, the resource would exist with id 1005 
and could then be pasted into the stack of your choice with 
Resedit. So, assuming this has all been done the next Step is to 
write the XCMD’s. 

At this point knowing exactly what you want the XCMD to 
do will save all sorts of frustration and reworking later (trust me). 
So, a small digression is in order as we set up the stack and decide 
what it is we want to accomplish with our array. 

First, and foremost, the book that everyone is talking about, 
Gary Bond's XCMD’s Гог Hypercard, should be your computer 
side companion if you want quick access to terminology, ex- 
amples and good programming style while writing your com- 
mands. Next, depending on the development system you are 
using open the HyperX... interface files to see the exact format 
that the procedures are written in since they aren't all written the 
same way that the examples in Gary Bond's book assumes (some 
pass the paramblock ptr in all procedures). 

For the sake of illustration and simplicity we will set up our 
stack in such a way that we will (1) fill the array with 60 values 
from some source (a quick and dirty method will be to use 
Hypercard's random number generator to generate 60 values) 
although these values could come from a field, an ask dialog, 
anywhere. 

(2) we will access these values in two ways 

(a) randomly-just to prove it works 

and (b) in sequence to fill in a graph. 

(3) as an added feature we will also continually update the 
graph described in 2b above so that new points can be added and 
the old ones removed. 

The above stack will require at least three but probably four 
XCMD's to fulfill it’s requirements. The first will fill the array 
RSRC with values on a random access basis. The second will 
retrieve values from the array and the third will create a ‘buffer 
array’ that will serve to save 60 data points- in the example stack 
this will hold the previous 60 points that the program generated 
so that they can be erased as the new points are plotted. This 
means that an additional ‘ANES’ RSRC must be created with a 
different id to serve as a buffer- but that is simply done with 
Resedit(copy/paste), and it's get info menu item. The fourth 
XCMD will then access the buffer array and not the working 
array to retrieve previous 'saved' values' 

Again, a slight digression is in order here, to stand back and 
see exactly what these items can allow us to do. In the example 
Stack, the array is somewhat simple minded, but with a little 
imagination, the possibilities of such a Resource are wide. For 
example, the id of all cards can be kept in the array to give a 
‘recording’ of movement throughout the stack, a record of any 
and all users of a stack can be kept, initialization values can be 
kept here, the buffer array can be huge so that it can be updated 
every time the working array is filled. Ok, maybe I' m the only one 
excited about all these possibilities, but hopefully some of you 
out there will be turned on too. 

So, the first XCMD to write will be the one to access the array 
at any point and fill in the data at that point. 

Ihavechosen to call it (in a fit of imagination and creativity- 
PUTDATA). The XCMD expects to receive two parameters- the 
time or array index and the value at that point. Below is the source 
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code of the PUTDATA xcmd: 


unit putdataXcmd; 
interface 
uses MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 
HyperXCMD, QDAccess; 


procedure putdata(ParamPtr: XCMOPtr2; 


inplenentation 
type 
timeDarray-erray[0..59] of integer; 
procedure arrayrsc(ParamP tr :XCMDPtr ); forward; 


procedure putdate(paramptr :xcmdptr); 
begin 

arrayrsc(paramptr); 
end; 


procedure arreyrsc(ParemPtr: XCMDPtr); 
var 
MY TIMEHAND : HANDLE ; 
REFNUM: INTEGER; 
TIMEARRAY : TIMEDARRAY ; 
temphandle : handle; 
tempstr :str255; 
hor iz, vert: longint; 
(жжжжжжжжжжжжжжх деї points XXXXXXXXXXXX) 
procedure getpoints€ paramptr 
hor iz, vert: longint); 
begin zerotopas(paremptr,paramptr^ .params[1]* , tempstr ), 
horiz:=strtonum(paramptr, tempstr ); 
zerotopas(paramptr,paramptr^.parems[2]^, tempstr); 
vert:sstrtonumCparamptr,tempstr); 
end; 
(oooooooocoeoeeceeeecceooeceeeooeeoerro) 
begin 
mytimehand :=(getresource( “АМЕ5”, 10052); 
hlock(myt imehand) ; 
blockmove(mytimehand* ,@timearray, sizeof (timearray)); 
getpoints(paramptr ,horiz, vert); 
if horiz > 59 then horiz := 59; 
timearray[horiz] := vert; 
blockmove(@timearray, mytimehand*,sizeof(timearray)); 
refnum:=curresf ile; 
changedresource(myt imehand); 
writeresource(myt imehand) ; 
re leaseresource(myt imehand) ; 
end; 
end. 


:xcmdptr;var 


The XCMD is lacking in many things, I didn't error check 
after the call to getresource so the user will have no way of 
knowing whether the call was successful or not. Also there is no 
check on the number of parameters passed to the XCMD- shear 
laziness I guess. But, assuming that the user is the one writing the 
XCMD it should be his/her decision as to whether or not to make 
this XCMD general enough for the public at large or specific to 
his/her application (the latter approach implies that the program- 
mer using the XCMD would be versed in it's parameter require- 
ments and would pass the correct values). 
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The second XCMD is very similar to the first, and in fact the 
two could be combined in such a way that a parameter check 
would tell if two parameters were passed indicating the user 
wanted to set the array value of param[1] to param[2] or if one 
parameter were passed indicating the user desired to retrieve the 
array value of param[1]. Again I've stuck with my original 
version of writing these things, not because they are better, but 
because they serve to indicate in some small sense, the evolution 
that these XCMD's have undergone and they serve to suggest a 
number of ways to improve upon and write better XCMD's. The 
second XCMD is titled *GetData' and expects one argument as 
a parameter- the value of the array index to be read. The result is 
passed back to Hypercard in the result field but could easily be 
placed in a global variable or field.(See Gary Bond's book for the 
gory details). 


unit getdataXcmd; 
interface 
uses MenTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 
HyperXCMD, QDAccess; 
procedure getdata(ParamPtr: XCMDPtr); 
implementation 
type 
timeDarray-erray(0..59] of integer; 
procedure arrayrsc(ParamPtr: XCMDPtr); forward; 
procedure getdata(paramptr :xcmdptr); 
begin 
arrayrsc(paramptr ); 
end; 
procedure arrayrsc(ParamPtr: XCMDPtr2; 
var 
MY TIMEHAND : HANDLE ; 
КЕРМОМ: INTEGER; 
TIMEARRAY : TIMEDARRAY ; 
temphandle:handle; 
а: integer ; 
tempstr :str255; 
hor iz: longint; 
procedure getpoints(Paramptr :xcmdPtr маг num: longint),; 
var tempstri:str255; 
begin 
zerotopas(paramptr,paramptr^.params[1]^,tempstr 1); 
hor iz:=strtonum(paramptr, tempstr 1); 


end; 

begin 
mytimehand :=(getresource( ‘ANES’, 100522; 
hlock(mytimehand); 


blockmove(myt imehand* , 8t inearray, sizeof (timearray)); 
getpoints(paramptr, hor iz); 
8:=timearraylhoriz]; 
longtostr(paramptr,a, tempstr ); 
рагатріг” .returnvalue := pastozero(paramptr, tempstr 2; 
hunlock(myt imehand); 
releaseresource(myt imehand); 
end; 
end. 


Again, no error checking on getresource or number of 
params. 

By themselves, or combined as a single XCMD, these 
examples will allow random access to a 60 point array from 
within Hypercard. The array size can easily be changed in the 
above examples and, in the initial resource definition, to allow 
any size array to be used—though I think the 32K limit also 
applies to resources. 

The third XCMDT' ve written is used to setup a buffer so that 
the initial array can continue to be updated while the ‘old values’ 
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are saved. An example of it’s use is in the example stack and has 
been described above. It’s call ‘DATABUFF’ and requires no 


parameters- assuming that the two array rsrc's are present in the - 


stack file and that their id’s are known. Clearly this approach does 
not allow much room for error but, with careful planning ,should 
not be much of a problem. 


unit databuffXcmd; 
interface 
uses MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 
HyperXCMD, QDAccess; 


procedure databuff(ParamPtr: XCMOPtr); 


implementation 
type 

timeDerray-array[2..59] of integer; 
procedure arrayrsc(ParamPtr: XCMOPtr2;forward; 
procedure databuff(paramptr : хстаріг >; 

begin 

arrayrsc(paramptr ); 
end; 


procedure arrayrsc(ParamPtr: XCMDPtr); 
var 
mytimehand, buf farrayH : HANDLE ; 
REFNUM: INTEGER; 
TIMEARRAY , buf farray: TIMEDARRAY ; 
temphandle:handle; 
tempstr:str255; 
horiz,vert:longint; 
numparams : integer; 


begin 

mytimehand := (getresource( “АМЕ5”, 10052); 

hlockCmyt imehand); ВІ 0СКМОУЕСМҮТІМЕНАМО” , @t imearray, 
SIZEOF CTIMEARRAY 2); 

releaseresource(myt imehand); 

buf farrayH:-Cgetresource( ‘ANES’, 10100); 

hlockCbuf f arrayH); 

blockmoveCbuf farrayH*, @buffarray, sizeof (buffarray)); 

buffarray := timearray; 

blockmoveCébuffarray,buffarragH^, sizeof (buffarray)); 


КЕРМИМ: =CURRESF ILE; 
changedresource (buf farrayH); 
wri teresource(buf farrayH); 
hun lock Cbuf f arrayH) ; 
releaseresource (buf farrayH); 
end; 

end. 


The fourth XCMD must be used with the databuff XCMD. 
It is actually a copy of ће XCMD ‘getdata’ with the exception 
that it accesses the buffer array (with a different id number) so 
that saved values can be read back and acted upon accordingly. 


unit getprevdataXcmd; 
interface 
uses MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 
HyperXCMD, QDAccess; 
procedure getprevdata(ParamPtr: XCMDPtr); 
implementation 
type 
timeDarray-array[8..59] of integer; 
procedure arrayrsc(ParamPtr: XCMDPtr); forward; 
procedure getprevdata(paramptr :xcmdptr); 
begin 
arrayrsc(paramptr); 
end; 
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procedure arrayrsc(ParamPtr: XCMDPtr); 
var 
MY TIMEHAND : HANDLE ; 
REFNUM: INTEGER; 
TIMEARRAY : TIMEDARRAY ; 
temphandle : handle; 
tempstr :str255; 
a : integer; 
vert,b: integer; 
horiz: longint; 
procedure getpoints(Paramptr :xcmdP tr; var ;num: longint); 
var tempstr 1:str255; 
begin 
zerotopas(paramptr, paramptr~.params[1]*, tempstr 1); 
horiz:=strtonum(paramptr, tempstr 1); 
end; 
begin 
myt imehand: =(getresource( “АМЕ5”, 101022; 
HLOCKCMYTIMEHAND); | 
blockmove(mutimehand",@timearrau,sizeof Ctimearray2); 
getpoints(paramptr,horiz); 
a:=timearrau[horiz]); 
longtostr(paramptr,a,tempstr); 
paramptr .returnvalue:=pastozero(paramptr, tempstr); 
releaseresource(mutimehand); 
end; 


end. 


Figure 1 is a table summarizing the syntax of the XCMD's 
and the id’s of the array resources. 


RESOURCE ID'S: 
ANES 1005 -This is the working array 
ANES 1010 -This is the buffer array 


XCMD SYNTAX: 
PUTDATA arrayindex,value 
-this XCMD expects two parameters, it will place the value parameter 
into the array at the position arrayindex. e.g. array[1] := value; 
GETDATA arrayindex 
-this XCMD expects one parameter. It will retum the value of the array 


at arrayindex in the Hypercard variable 'the result’ 
eg aray[arrayindex] := theresult; 

DATABUFF 
this XCMD has no parameters passed with it. It takes the values in the 
array represented by Resource 1005 (the array the user manipulates in 
the above two calls) and places them in the arrau represented by RSRC 
1010. 

GETPREVIOUSDATA arrayindex 
-this XCMD is identical to the GETDATA XCMD in that it is passed a 
single parameter -arrayindex and it accesses the buffer array (id 1010) 
to get its’ value (which is also returned in "һе result’). 


Figure 1 


Well, that's about it for the XCMD’s. There is a lot of room 
for improvement here and I believe a lot of room to explore. I’ve 
included the XCMD's and an example stack that demonstrates 
their use as well as the Hypertalk method of using an array. I 
apologize again for my lack of programming expertise and hope 
that it doesn’t detract from the overall article. I would like to write 
another article in the near future that gives a few tricks to use the 
third party product “Programmer’s Extender” in XCMD’s in 
order to save even more time and effort in writing XCMD's- let 
me know if anyone is interested in this. 

The example stack contains three buttons: 

The first will demonstrate the use of a Hypertalk array in the 
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best way I know how - it's entitled “the old way” and basically 
initializes 50 lines of an invisible card field to some random 
number . 
It’s script is as follows: 
on mouseup 
put 1 into linecount 
repeat(50) 
put random(58) into line linecount of cd fld “array 
put linecount * 1 into linecount 
end repeat 
end mouseup 


The user can then access any point in the array with the 
button “get data"- it's sript is as follows: 
on mouseup 
ask “what point’ 
put line it of cd fld “array” 
end mouseup 


The next card will do basically the same thing except it will 
use the XCMD’s Putdata and Getdata. 


The script of cd btn "new way" is: 
on mouseup 
put 1 into linecount 

repeat(50) 

putdata linecount,rendomC50) 


put 1 * linecount into linecount 
end repeat 
end mouseup 


The script of card button “get data” is : 


on mouseup 

ask “what point” 

put the result into pointvar 
put getdata pointvar 
end mouseup 


The final card will draw a graph of points - the horizontal 
coordinates will represent the array index and the vertical will 
represent the array index value. 

It demonstrates the use of the databuff XCMD in that the 
graph will be continuously updated until the user presses the 
mouse button. 

Well, that’s it for my first attempt at sharing the few things 
I’ve learned about Macintosh programming. If there are ques- 
tions my address is 


915 N. Bolton Ave 
Indpls., In. 46219. 
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Reinventing the wheel often provides an opportunity to 
embellish on the original design. Recently, Ineeded a file dump 
utility. Several packages are available “over the counter”, but I 
needed a utility that dumps the entire file without having to 
manually move from sector to sector as is the case with most 
commercial solutions. Moreover, I use file dump tools fre- 
quently enough that I could afford to spend the effort writing one 
for Hypercard. 

I dump the file in a fairly typical way. Each line іп the dump 
contains the “sector address” of the first byte on the line followed 
by the hexadecimal dump of 16 bytes followed by the ASCII 
interpretation of the data. Not all ASCII characters are “print- 
able” so we replace non-printing characters with the “.”, yielding 
a cleaner display. 

This month’s XFCN, FilePeek.c (listing 1) accepts two 
parameters. The first parameter is the reference number of the 
opened file; the second parameter is the sector you want dumped. 
HFS sectors are 512 bytes so filepeek returns 32 lines of 16 bytes 
apiece. 

Dumping the entire contents of a file becomes a matter of 
calling FilePeek repeatedly for all the logical sectors in the file. 

The first line in the dump tells us how many bytes were read 
in. This number can be equal to or less than a full sector. If line 
1 contains less than a sector full of data, then you know that 
logical end of file is after the last byte read in. 

The Hypertalk afficianado will realize that this code can 
easily be written in Hypertalk. I chose to commit my scheme to 
an XFCN only after discovering that the Hypertalk version was 
too slow for my purposes. 

The dumping scheme is amazingly simple. Position the file 
mark at the beginning of the sector that you want to dump. If the 
Start of the sector extends beyond end of file, do nothing and 
return to hypercard with a result of zero (no bytes were read in), 
otherwise read the sector into the buffer we allocated (buf). 

The sector is presented to Hypercard as a series of haxadeci- 
mal characters. Hypercard contains a call back “NumtoHex” 
which converts an arbitrary run of data to a hex string. We lose 
portability when using a callback so you’ll need to write your 
own hexdump algorithm or dig one up in the toolbox. 

FilePeek dumps two bytes at a time (4 hex digits). This is 
analogous to dumping the contents of a short. We can use a 
pointer to short (rPtr). To dump the ascii data, we use a char 
pointer (cPtr) to the same data. 

The current line in the dump is assembled by first displaying 
the “sector address” of that line. The sector address is 512 * blk 
(blk = sector number). 

The sector address is delineated by the “:” character. Fol- 
lowing the sector address, we display 16 bytes of data in hexa- 
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decimal format. The data is grouped into 8 words. 

The hexadecimal data is followed by the ascii representation 
of the line. If the character falls in the range of printing 
characters, we display the character, otherwise print a “.”, 
Characters below the space (0x020) are not normally considered 
printing characters. Likewise, Inside Macintosh indicates that no 
characters above $D8 have a printable format. Using the period 
to represent non-printing characters results in a less-cluttered 
looking dump. 

We need to cycle the character pointer, cPtr, twice for every 
cycle on rPtr (a character is half a word). We accumulate the ascii 
data into a separate string which we then concatenate onto the end 
of the hex data. 

Once the current line is assembled, we stick a carriage return 
on the end, block move it to the output data handle and then go 
to the next 16 bytes in the input stream. When the outer loop 
completes, outdata will contain 32 lines of 16 bytes apiece, 
suitable for framing. 

How you open and close a file from Hypercard is a matter of 
taste. I prefer to keep my interface to the file manager as clean 
as possible. This requires passing a filename and working 
directory id to the file manager’s FSOpen call and subsequently 
referring to the file by the reference number returned by FSOpen. 
To close the file, pass the reference number to FSClose (last 
month I provided an XFCN that will return a file name and 
working directory id from the standard file package). 

Listings 2 and 3 are two simple XFCNs that open and close 
afile respectively. FileOpen returnsa reference number if the file 
opened ok (0 otherwise). Pass this reference number to FilePeek 
along with the number of the sector you wish to dump. 

Figure 1. is a sample card that I use to dump the contents of 
the file. The dump is presented in a mono-spaced font to keep it 
"clean-looking". The forward and back arrows allow the user to 
“browse” sectors by moving 1 sector forward or backward. The 
scripts for theses two buttons is fairly obvious so I’ve left them 
to the reader. The scripts for open, close are contained in listing 
4. 


= file open button 

on mouseUp 
global fileName, DirectoryID 
global fileRefNum, theSector 


put getFileNameToOpen() into it 

put item 1 of it into fileName 

put item 2 of it into DirectoryID 

put filename into card field “file name” 


if filename is not empty then 
Put FileOpenC fileName, DirectoryID ) into fileRefNum 
end if 
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Hupercard File Dump Utility 


File Name: 
Dump of Sector: ИШ) 
Number of Butes in this Sector: 


: ҒА 2А2А QAM 2А2А 2А2А AAAA 2KM2A А Нн | Су 
000010: 2A2A 2Ж2А AMA 2AA ZAZA 2A2À 2АЗА ЭКА. жашта 

000020: 2AZF (ОҒ 2А20 4669 6С65 3A20 4669 6065 */./* File: Pile PTF 
000030: 5065 656B 2PS3 0909 0909 2A2F (ОҒ 2A9 Peek.c....*/./*. ii 

000040: 0909 0909 0909 092A 2700 272А 204? 69% ....... */./* Giv ЇЇ! 

000050: 656E 204 6865 2073 6563 MEF 7220 696E en the sector in |1: 

000060: 6465 7820 696E MEF O9QÀ ZFOD 2Р2А 2061 dex irko.*/./* a |11 
000070: 6Е20 6378 6973 7469 6567 2066 696C 692 n existing file, [h 
000080: 2072 6561 6420 7468 6320 092А 270) 2Р2А reed the .*/./* ii 
000090: 2073 6563 MEF 7220 696E 2061 6064 2022 sector in end ^ H 
000040: 6475 6070 2220 6974 2074 EFO 2AF (ROT dump" it to.*/./ EH 
000080: 2А20 "M68 6520 7363 7265 Є5БЕ 0909 0909 * the screen... |11: 
0000С0: 092A ZFOD 2Ғ2А 0909 0909 0909 0909 AZF .*/./*........ e p 
000000: ООР 2A20 5061 7261 GI 6572 733А 0909 ./* Peremters:.. ||: 
: 0909 092A ZFOD ZPAA 2070 6172 6160 3020 ...*/./* раға 

: 3020 6669 6065 2072 6566 6572 ESEE 6365 = file refererce о 


Ka = 


Figure 1 


end mouseUp 


- Go to Sector 
on mouseUp 
global fileRefNum, theSector 


if filerefnum is empty then 
answer “You have to open a file first, silly!” 
else 


ask "Read what sector?” with 707 


if Cit is not empty) then 
put it into theSector 
Peekat theSector 
end if 
end if 


end mouseUp 


- file close 
on mouseUp 
global fileRefNum 


put FileCloseC fileRefNum ) into it 
— ignore the result of a closed file 


end mouseUp 


Listing 4. Scripts for the buttons 


An interesting variation on this theme would be to dump the 
files in reverse order so that it prints in ascending order on the 
LaserWriter. Several easy solutions exist for this problem, and 
I'll leave it as this month's exercise to the reader. As a hint, I can 
think of two ways to do this off hand, one easy but inefficient, the 
seconda little more challenging: (1) create acard for every sector 
(make sure your file is small first!) or (2) Find out how many 
sectors the file contains before starting the dump ( a wonderful 
opportunity to try your hand at XFCN writing). 


Note on a bug in last month's article: 
Last month’s XFCN, GetFileName, incorrectly returns the 
working directory id of the file selected from SFGetFile. Change 
the call to GetFileNameToOpen to Read: 
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if( GetFileNameToOpen( typs, numTypes, FileName, &F ileWDID ) )( 
temp = Clong)FileWDID & OxFFFF; 
NumToStrC paramPtr, temp, &WDIDString 2; 
PtoCstrC WDIDString ); 


i —— s ——ə s=zƏsc,csv1z1@ -KK— — — a 


Listing 1: FilePeek.c 


ЫЫ 


/* File: FilePeek. С х/ 


/* Given the a index into */ 
/* an existing file, read the*/ 
/* sector in and “dump” it to*/ 


/* the screen x / 

[* ы | 

/* Paramters: x / 

/* param® = file reference num */ 


/* (file is open 2 */ 


/* param! = sector number %/ 
/* (1 sector = 512 bytes)*/ 
/* -“ 

/* To Build: х/ 

/* x/ 


/* (Ы Create a project using*/ 
/* this file as well as the */ 
/* XCMD.Glue.c file. (Set x/ 
/* project type to XCMD Cor */ 
/* XFCN) from the ое! menu. */ 


/* 

/* (2) Bring the project up to */ 
/* date. 57 

/* x 

/* (3) Build Code Resource. */ 
/* x 


/ 
/* (4) Use ResEdit to copy the */ 


/* resource to your stack.  */ 
[**XXx XXX X XXX XXXCEEEXOOEXEEXXXXJ 


S include 
"include 
* include 
* include 
Sinclude 
Sinclude 
*include 
®include 
* include 


def ine 
Sdef ine 
tdef ine 
tdef ine 
"def ine 


«MacTgpes .h? 
‹050411.№ 
«MemoryMgr .h? 
«FileMgr.h? 
«ResourceMgr .h? 
«равса1.һ» 
«strings.h? 
“Hyper XCmd . h^ 
*HyperUt ils.h^ 


SECTOR 

NUMROWS 
NUMLINES 32 
NUMBYTES 16 
SPACE 


512 /***size of input buffer ***/ 

8 /***across each line***/ 
/***lines of data ***/ 
/***tibytes per row of data***/ 

0х020 /***the space character***/ 


long paremtoNum(); 
void appendChar C); 
void CopyStrToHandle(); 
char *CopuAscii(); 


pascal void main. paramPtr ) 
XCmdBlockPtr paramPtr; 


short 
short 
short 
short 
long 
long 
Handle 
short 
char 
char 


err; 
fref; 
lc; /* line count */ 
rc; /* row count х / 
cnt; 
blk; /* sector number %/ 
outData; 
*rPtr; /* per row x/ 
*cPtr; /* for ASCII x/ 
*aPtr; /* points to asciival */ 
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char *buf; 

char  esciiStr[32]; 
char — curntLine[256]; 
91731 | num$String; 


outData = OL; 
1fC paramPtr->paramCount == 2 X 
/*** expect two parameters ***/ 
/*** (1) Get our input parameters ***/ 
fref = Cshort)paramtoNum( paramPtr, 0 ); 
blk = peremtoNumC paramPtr, 1 2; 


/*** (2) Read a buffer of data X ***/ 
blk = blk * SECTOR; 
err = SetFPosC fref, fsFromStart, blk ); 
if С lerr )( 

cnt = SECTOR; 


/*** We need to keep this data locked ***/ 
/*** Since we can;t trust callbacks not ***/ 
/*** to move stuff, we allocate the ***/ 
/*** buffer as non-relocatable. жж» / 

buf = NewPtr( cnt ); 
err = FSRead( fref, &cnt, buf ); 


if С err != noErr && err != eofErr X 
paramPtr->returnValue = ØL; 


return; 
) 
/*** result is returned to hupercard as ***/ 
/*** a null terminated string xxx / 


outData = NewHandleC ØL ); 


/*** (3) Start filling the output buffer***/ 
*curntLine = 40”; 


/*** first the number of bytes read in ***/ 
NumToHex€ paramPtr, cnt, 4, &numString 2; 


appendChar( PtoCstr( (char *)&numString), “Vr 2; 
CopyStrToHandleC &numString, outData ); 


/*** point to the input data ***/ 
rPtr = (short *Obuf; 


forc 1с = 0; 1c < NUMLINES; **lc X 
*curntLine = 40” 


/*** bik is the sector address ***/ 
NumToHexC paramPtr, blk, 6, &numString ); 
PtoCstr( (char *)&numString ); 

strcat( curntLine, &numString ); 
appendChar( curntLine, ‘:’ ); 

аррепаСһаг( curntLine, SPACE ); 

aPtr = asciiStr; 

blk += NUMBYTES; 


forc rc = 0; rc < NUMROWS; **rc X 
/*** convert eight shorts per row  ***/ 


/*** if we overrun the buffer, draw ***/ 
/*** whatever data follows it... ***/ 


NumToHexC paramPtr, Clong)*rPtr, 4, &numString); 
StrcatC curntLine, PtoCstrC (char *)&numString)); 


appendChar( curntLine, ' ' 2; 


cPtr = (char *)rPtr; 

aPtr = CopyAsciiC aPtr, *cPtr++ ); 
= CopyAsciiC aPtr, *cPtr** ); 

rPtrt+; 
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*aPtr = 40”; /*** terminate the ascii data ***/ 


strcat( curntLine, esciiStr ); 
appendChar( curntLine, ‘\r’ ); 


/*** move line into output buffer ***/ 
CopyStrToHandle( curntLine, outData ); 


DisposPtr( buf ); 


cnt = GetHandleSizeC outData ); 
*(XoutData + cnt) = 40” 
paramPtr->returnValue = outData; 


) 


long paramtoNum( paramPtr, i ) 
XCmdBlockPtr paramPtr; 
short i 
[***xxxxxxxkkxxkkkxoooeeer 
* Given a handle to an input 
* argument in the paramBlk 
* return an integer representation 
* of the data. 
x 


XEXXCOCOOOOODODOEEEGEXEE KEES / 


( 
54731 theStr; 


HLockC paramPtr->params[ i ] ); 


ZeroToPas( paramPtr, *(paramPtr->params( i ]), &theStr ); 


HUnlockC paramPtr->params[ i ] ); 
) return( StrToLong( paramPtr, &theStr ) ); 


void appendChar( theStr, theChar ) 
cher *theStr; 
char theChar ; 

Ы 25 522222522222 

* append the character passed 


* to the end of the string 
KEXEXEEXEXEXEOOOEEXEXEXX/ 


long Теп = strlen( theStr 2; 
char *theEnd; 


theEnd = theStr + len; 
*theEnd** = theChar; 
*theEnd = ‘\9’; 


char *CopyAsciiC outStr, theChar ) 
cher *outStr; 
char theChar ; 
/YFKEXXXXXXXXXX312XXXXXXXXXX 
* if the character passed 
* in the input stream is a 
printing character, append 
it to the output string, 
otherwise, append the ‘. 


return the update output 
string. 


x 
x 
x 
x 
x 
x 
XXX XXXX3XXXEXXXEXXXXXXEXEEXXEX/ 


1f С theChar >= SPACE && theChar <= 0x0D8 ) 


*outStr** = theChar; 
else 
*outStr*t* = '.^; 


return( outStr ); 


void CopyStrToHandleC theStr, hand ) 
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char *theStr; 

Handle hand; 
/BERERERAAAAAAE EERE RAKES 
* Copy the input data to the 
* output handle. 
x 


522222222222222222224 224) 


( 
longcnt = strlen( theStr ); 


longoldSize = GetHandleSize( hand ); 


SetHandleSize( hand, oldSize + cnt ); 
BlockMove( theStr, *hand + oldSize, cnt ); 


Listing 2: FileOpen.c 


Жжжж 
/* File: FlleOpen.c */ 
27 


/* open the file whose name and */ 
/* working directory id are */ 
/* passed as parameters. This */ 
/* information can be obtained */ 
/* using GetFileNameToLoad.. .*/ 

*/ 


Li 


/* convert the wdid to a usable form */ 

HLockC paramPtr->params(1) ); 

ТегоТоРав( paramPtr, *CparamPtr->params([1]), &str ); 
HUnlock( paramPtr->params[1] ); 

wdid = CshortoStrToNumC paramPtr, &str ); 


ifC FSOpen( &fName, wdid, &refnum) == noErr ) 
NumToStr( paramPtr, Clong)refnum, &str ); 
else 
NumToStr( paramPtr, OL, &str ); 


paramPtr-»returnValue = PasToZero( paramPtr, &str ); 


sting 3: FileClose.c 


[3 XXXXEEEXEXXXXXXXXXXXEEEXXXXEEEXX/ 


/* File: FileClose.c x/ 

/* */ 

/* XCMD to access the file mgr */ 
/* call FSClose */ 

/* Paramters: x/ 

/* param® = file reference from*/ 


the fileopen xcmd х/ 
қанын ны ныса — х/ 


ХХХХХХХХАХА AAAS AAA ХХХ ХХХ ХХХ / 


/* 

/* Paramters: x / 

/* paramü = file name num */ 
/* parami = directory id */ 
[* */ 

/* Qut: x/ 


/* File RefNum if opened, 0 */ 
/* otherwise 


tinclude 
Sinclude 


*/ 


*/ 


ХХХ ххх ХХХ ХХХ ХХХ / 


«МасТурев.һ» 


«0SUtil.h? 


t include 
Sinclude 
Sinclude 
Sinclude 
Sinclude 
8include 
Sinclude 
Sinclude 
Sinclude 


«MacTypes .h> 
«0SUtil.h» 
«Memor yMgr . h>? 
«FileMgr.h? 
«ResourceMgr .h? 
«равса1.һ» 
«strings .h> 
“Hyper XCmd .h” 
“HyperUtils.h” 


pascal void main. paramPtr ) 


Sinclude <MemoryMgr .h> 
Sinclude «FileMgr.h? 
Sinclude <ResourceMgr .h) 
Sinclude ‘pascal .h> 
"include <strings.h> 
Sinclude “HyperXCmd.h’ 
Sinclude “HyperUtils.h’ 


pascal void main( paramPtr ) 
XCmdBlockPtr paramPtr; 


char *filename; 
Str31 str, fName; 
short wdid, refnum; 


HLockC paramPtr-»params[£2] ); 
ZeroToPas( paramPtr, *(paramPtr-— perems[0]), &fName ); 
HUnlockC paramPtr-»params[2] ); 


XCmdBlockPtr paramPtr; 


short . refnum; 
cher  str(256]; 


/* convert the refnum to a usable form */ 

HLockC рагатРіг-› рагатѕ (0) ); 

ZeroloPas( paramPtr, %(рагатРіг->рагатв(010, &str ); 
HUnlock( рагатР{г-› рагатѕ (0) ); 

refnum = (short)StrToNum( paramPtr, &str ); 


/* Normallu we should check the result*/ 
/* code but it won’t kill us to ignore*/ 
/* the resit of a close file call */ 
if С FSCloseCrefnum) 2 


<— 


paramPtr-)returnValue = OL; Cag! 
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HyperChat™ 


XCMD Corner: HFS Tree Climbing Hypercara 


Hyper Lite 

In keeping with the spirit of the summer season, this month’s 
XCMD is light and easy. Not too long ago, I promised to provide 
an XCMD that, given the name and directory id of a file, returned 
that file’s full pathname. Such a utility is eminently useful in the 
current incantation of Hypercard. 

Hypercard is fully capable of opening a file, reading and 
writing its contents and then closing the file. Unfortunately, 
unless you know the full path name of the file, you are limited to 
accessing files in Hypercard’s working directory. 

One of the first published XCMDs was a little gem from 
Steve Maller of Apple Computer Inc. that eliminates this 
MSDOS-compatible feature of Hypercard. Steve’s FileName.p 
presents the user with the standard file package and returns the 
full pathname of the file specified. 

If you are a regular reader of this column, you'll recall that 
I translated Steve’s XCMD from pascal to “C”. You also know 
that my version lost something in the translation. Rather than 
return a full pathname, GetFileName.c returns the file’s name 
and working directory id. I felt this was more useful because the 
file’s name and wdid open up access to most of the file manager 
calls for the XCMD programmer. Still, if you want to continue 
to use Hypercard’s built-in file I/O, getfileName won’t be of 
much use since it doesn’t return the full pathname required by 
hypercard. 

Listing 1 (FullPathName.c) is a simple XCMD that accepts 
the filename and working directory id as input and returns the 
fullpathname of the file as output. 

As is often the case, this XCMD first converts the input data 
from c-string format to pascal strings and numbers as needed. 
Note that the default return value will be the name of the file that 
was passed іп param[0]. 


A Review of HFS 

As a rule, we don’t come into contact with full pathnames 
very often on the Macintosh so the format may require a little 
explaining. If you want to explore the Hierarchical File System 
in greater detail, take the time to read Chapter 19 of volume IV 
of Inside Macintosh. If you don’t have volume IV handy, the 
following discussion will get help you understand the code. 

Devices that can store and retrieve data on the Macintosh are 
called “volumes”. Files are organized on volumes in folders. 
Folders can contain other folders yielding a hierarchical or “Tree 
structure”. The order in which folders are stored in this tree 
structure specify a path to any file that is contained in that folder. 

The rootof this tree is the volume name. If we stick a “:” onto 
the end of the volume name, we have the beginning of a full 
pathname. In other words full pathnames always start with the 
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volume name. Each path in the pathname is delineated by the '*:". 
Thus, Hd:folder:file specifies a valid pathname. The last item in 
the pathname is the name of the file itself. The folder that holds 
this file is referred to by a unique directory id. When the user 
selects a file using SFGetFile or SFPutFile, the file manager 
returns the file’s name as well as the directory id. For historical 
purposes, the directory id is stored in the vRefNum field of the 
reply record. This little tweak is how Apple was able to make 
HFS backward compatible with the flat-file system. 


Tree Climbing 

The folder that contains the file represents the deepest node 
on the tree. The next folder up the hierarchy is called the parent. 
Knowing the parent's id, we can call PBGetCatInfo to get its 
name as well as the directory id of its parent folder. We climb the 
tree by continuously feeding a parent directory id into PBGet- 
CatInfo until we detect an error (no more folders on this path). 

Tree climbing suggests recursion. The routine ClimbTree in 
Listing 1 calls PBGetCatInfo to get information about the direc- 
tory whose id was passed in. We kick it off by first getting 
information about the folder that holds the file. This is the 
directory whose id was returned in the reply record. 

Each activation of climbTree uses the same catalog parame- 
ter block (cpb) which was allocated in the stack frame of 
FullPathName. This is legal because the only information that is 
unique to each activation is the directory id (passed as a parame- 
ter in child) as well as a pointer to the string the PBGetCatInfo 
uses to store the folder's name. Each activation allocates mem- 
ory for the name string and sets cpb's ioNamePtr field to point 
to its own copy of the string. 

I allocate the string, folder name, in the heap and point to it 
on the stack because successful recursion dictates that one be 
mindful of the stack at all times. Even if there is no danger of 
overflowing the stack, a little defensive programming goes a 
long way. 

A nice feature of the recursion is that we can build the string 
in forward order. Although we walked the tree backwards, we 
don't actually put the full pathname together until we reach the 
root which is detected by discovering that it has no parent folder. 
Once we reach the root, the stack unwinds in the order of root- 
»parent-»child-»filename. 

The following script, working with GetFileName.c (See 
Mactutor Vol. 5 No. 6) returns the full pathname of a file selected 
via standard dialog: 


on mouseup 
put getfilenametoOpen() into it 
if item 1 of it is not empty then 
put FullpathnameCitem 1 of it, item 2 of it) into it 
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end if 
end mouseup 1fC PBGetCatInfoC cpb, 0) == noErr X 
ClimbTreeCcpb-? dir Info. ioDrParID,cpb,ful1Name); 
Because Hierarchical File System can't handle pathnames Concat( (char *fullName, (char *)folder-name ); 
longer than 256 characters, I limit the string returned by Fullpa- Concat( (char *)fullName, (char *)&colon ); 
thname to 256 characters. If you want to return the full path 
regardless of length, you can modify the concat routine in 
“HyperUtils.c” to “grow” the output string on demand. ) 


DisposPtr¢ folder_name ); 


pascal void main( paramPtr ) 


Listing: FullPathNene.c XCmdBlockPtr paramPtr; 


рока какаа / ( 

/* File: FullPathName.c x/ Str31 str. fName: 
/* Given the name and work ing*/ short wdid: j 
/* directory of & file, walk the*/ WDPBRec theWDPB : 
/* directory tree to determine */ CInfoPBRec  theCPB: 
/* what the full pathname of the*/ HParamBlockRec theHPB; 
/* directory is... gi char fullPath[(256]; 
/* Paramters: */ char part_Name[256]; /*** used in HPB ***/ 
/* param = file name num — */ cher  vol-Name[2561; 
/* рагамі = directory id */ 05Егг егг: 
/* Out: */ | 

/* full pathname of the working*/ colontg] = 1: 

/* directory x/ colon([1) = (t 

/* Once again, I am indepbted to*/ 

/* Steve Maller of Apple */ vol.Name[0] = 40”; 


/* Computer Inc for illuminating*/ 
/* this oft too dark realm of*/ 

/* the toolbox. x/ 
[***5XXXXXXXXXLbE ХХХ ХХХ AAA AAA ALE / 
Sinclude <MacTypes.h> 

include “OSUtil.h> 

Sinclude <MemoryMogr .h> 

Sinclude «FileMgr.h» 

Sinclude <ResourceMgr .h) 
Sinclude <pascal.h) 

include <strings.h) 

Sinclude <hfs.h) 

Sinclude "HyperXCmd.h^ 
Sinclude "HyperUtils.h"^ 

Sdefine nil OL 


part. Мәпле(01- ‘\9’; 
/*** empty is the default answer ***/ 
paramPtr->returnValue = ØL; 


HLock( paramPtr->params[@] ); 
ZeroToPas( paramPtr, *(рагатРіг-›рагатѕ [0 1), &fName ); 
HUnlock( рагатРїг-› рагатѕ [0] ); 


/*** convert the wdid to a usable form ***/ 

HLock( peremPtr-»perems[1] ); 

ZeroToPas( paramPtr, *CparamPtr->params[1]), &str ); 
HUnlockC paramPtr->params[1] ); 

wdid = StrToNumC paramPtr, &str ); 


/*** First, we appeal to GetVInfo to get***/ 

LE E. /*** volume name that the file lives on ***/ 

cher  colon[2] = *ip:^; рагі Мате [0] = “0°; 
theHPB.volumeParam.ioNamePtr = (StringPtr)vol_Name; 

шылы аса аш theHPB.volumeParam.ioVRefNum = (short)wdid; ' 
ong child; 


CInfoPBPtr cpb; theHPB.volumeParam.ioVolIndex= 0; 


a, 1fCPBHGetVInfoC &theHPB, Ø) != noErr ) 
/ return; 


* Climb the directory tree 


* until we reach the root /*** Next, use the working directory info ***/ 


* Allocate the records in the /*** to walk the directory tree backwards ***/ 
* heap to keep the stack frame /*** to the root directory xxx / 
: ° 522... Too theWDPB.ioNamePtr = (StringPtrOpart. Name; 
r theWDPB.ioVRefNum = wdid; 
: оо case of terminal theWDPB ioWDProcID А д; 
; M. theWDPB. ioWDIndex = 0; 
* child is the working directory 1#С PBGetWDInfoC &theWDPB, 0) != noErr ) 
х id of the “current folder", vol return; 
* is the volume reference number and 
: 4... to the fullPath(@] = ‘\0’; 
output String theCPB .dirInfo.ioFDirIndex = -1; 
dz c RE аа NN theCPB .dirInfo.ioVRefNum- theHPB.volumeParam.ioVRefNum; 
StringPtr folder_name= (StringPtr )NewPtr( 256 2; ClimbTreeC theWDPB. ioWDDirID, 
/*** setting the file directory index to -1***/ CCInfoPBPtr2& theCPB, 
/*** lets us get information about the ***/ (Str ingPtr)fullPath ); 
/*** directory whose id is specified in the***/ 
Р Bee Nac the parameter block***/ /*** Climbing the tree yields the names of ***/ 
older.neme z ; /*** all the folders which we still need to ***/ 
cpb->dirInfo.ioNamePtr= (StringPtr)folder_name; /*** add the file’s name to. xxx / 
cpb-»dirInfo.ioDrDirID- child; Concat( (char *)fullPath, (char *)&fName ); 
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paramPtr->returnValue = PasToZero( paramPtr, fullPath ); 


Listing: HuperUtils.H 

/ **XoXxXocoooeoooocpeboooopboeoeboocoeee / 

/* HyperUtils.H х/ 

/* Header file for HuperUtils.c*/ 

/* routines... */ 
/^Ж^ЖЖЖЖЖХҖХЖЖХЖХЖАЖЖЖАЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ / 

Sdefine NIL ØL 

Sdefine UPFRONT -1L 
voidCenterWindow( WindowPtr wptr ); 
voidConcat( char * stri, char * str2 ); 
void CopyPStr( char * рбігі, char * pStr2 ); 
short GetFileNameToOpen(SFTypeList typs,short typcnt, char 
*theName, short *theWDID); 


Listing: HyperUtils.c 

Г **xXxcooceeceooeocecceeoceeoeeee / 
/* HyperUtils.c */ 

/* A collection of useful */ 
/* routines... */ 
[xx ХХХ ХХХ ХХХ ХХХ ХХХ / 
$include «МасТурев.һ» 
Sinclude “0OSUtil.h> 
Sinclude <MemoryMgr .h> 
Sinclude <FileMgr .h» 
Sinclude <ResourceMgr .h» 
Sinclude <StdFilePkg.h» 
Sinclude "HyperXCmd.h" 
Sinclude “HyperUtils.h” 


voidCenterWindow( wptr ) 

WindowPtr  wptr; 
/®*Ж®Ж^ХЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
Center а window in the current 
screen port. Note: Does not 
attempt to work with multi-screen 
sustems. 
This code is inspired bu a 
similar routine written bu Steve 


Maller in MPW Pascal. Thanks Steve. 
XXCOOOOOOOODOOOOOOODOEOOEOEEX XE / 


% © MH MH мм мм 


short hWindSize = wptr->portRect.right - wptr->portRect. left; 
short vWindSize = wptr->portRect.bottom - wptr->portRect. top; 
short hSize = wptr->portBits.bounds.right - wptr- 
yportBits.bounds.left; 

short vSize = wpotr->portBits.bounds.bottom - wptr- 
yportBits.bounds.top; 


MoveWindow( wptr, ( hSize - hWindSize ) / 2, 
) ( vSize - vWindSize + 20) / 2, false); 


void Concat( stri, str2 ) 

char *str 1; 

char *str2; 
/*%Ж*ЖЖЖЖЖЖЖЖЖАЖЖЖЖЖАЖАЖЖЖЖЖЖЖЖЖЖ 
* Append string 2 to the end of 
* string 1. Both strings are 
* pascal-format strings. 
* stri must be large enough to hold 
* the new string and is assumed to 
x 
x 
( 


be of Type Str255 (a pascal string) 
XKKXXXXXXXXXKEXXXXXXXXKXKKKXK/ 


short len! = *str1;/***number of chars in string 1***/ 
short len2 = *str2**;/*** number of chars in string 2***/ 
char *temp; /*** string pointer ***/ 


{fC Теп! *len2 > 255 ) 


len2 = 255 - leni; 
xstrl++ += len2 ; /***add sizes together to get new size***/ 
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temp = stri + leni;/*** move to end of string 1***/ 
while( len2 )( 
Xtemp++ = *str2++; /*** add char to temp and move along***/ 
-Теп2; /*** until all characters are added***/ 


) 
) 
voidCopuPStr( pStri, pStr2 ) 

char *pStr1; 

char *pStr2; 
/Ж*ЖЖЖЖЖЖЖХЖХЖХЖХЖЖЖЖХЖЖХЖЖЖЖЖЖЖЖЖЖ 
ж Copy the contents of рвігі into 
x pstr2. The strings are assumed 
* to be of type STR255 (length byte 
* precedes data 
EXOOOOOOOOOOOOOOEOEOOEE AEA EY / 


( short i; 
char *tstr; 


tstr = pStr2; 
fore i = 0; i <= *pStri; i++ ) 
*tstr++ = *pStr i++; 


short GetFileNameToOpen( typs, typCnt, theName, theWDID ) 
SFTypeList typs; short  typCnt; 
cher  *theName; short — *theWDID; 
Ы 52 55 5 555222222222. 
* Invokes SFOpenFile to query the 
* user for the name of a file to open. 
* In: List of types of files to 
х filter for Cup to 4) 
* Out: fileName if picked in theName 
* working directory in theWDID 
Ж nil otherwise 
* the file's volum ref num. 
* ( Note that the space for the 
* string must be allocated by the 
x 
x 
( 


caller). 
ХХХХХХХХХХХХХХХХХАХ ХХХ EXE / 


Point where; 
cher prompt(1); 
SFReply reply; 
GrafPort *oldPort; 
WindowPtr  dlogID; 
prompt [£) = 40” 
/*** Get and put up the standard file ***/ 
/*** dialog. You will only see the file***/ 
/*** types that you filtered for. If ***/ 
/*** you filtered for no files, then ***/ 
/*** all files will display +; 
GetPort( &oldPort ); 
dlogID = GetNewDialog( (short)getD1gID, CPtr NIL, 
(Ptr UPFRONT ); 
SetPort( dlogID ); 
CenterWindowC dlogID ); 
where.h = dlogID- portRect . left; 
where.v = dlogID->portRect. top; 
LocalToGlobalC &where ); 
SFGetFileC where, prompt, CPtrONIL, typCnt, typs, (PtrONIL, 
&reply ); 
DisposDialog(C dlogID 2; 
SetPort( oldPort 2; 
/*** [f the user selected a file, let’s ***/ 
/*** get the information about it ***/ 
if Creply.good) ( 
*theWDID = reply.vRefNum; 
PtoCstr( (char *O&reply.fName ); 
strcpy( theName, &reply.fName ); 


returnC reply.good ); 


HyperChat™ 
The Blessed Folder 


A colleague related an interesting experience that occurred 
to him at MacHacks this year. He asked an Apple Engineer 
whether he could mount Appleshare volumes under program 
control. The engineer asked him why he’d want to and went on 
to explain that it’s simply not something you do. If you need to 
mount Appleshare volumes, use the chooser. 

This struck me as odd because Гуе always believed that your 
programs should be able to do anything that the user can do. 

Imagine some inexperienced user being told that “the server 
has unexpectedly shut down”. Consider the options that this error 
message presents to the uninitiated: Ask someone what’s going 
on, call Apple's customer service department or read the manual. 

Each one of these options punishes the user fora mistake that 
he or she did not make! Why not have a little task running 
somewhere that tries to reconnect the user and, failing that, alerts 
the poor soul that they may have to visit the chooser to regain 
access to the server? 

Perhaps too many people at Apple are falling into that old 
trap of believing in everything they read. The human interface 
guidelines should be just that, guidelines. When you start taking 
guidelines as gospel, you start closing the door on creativity and 
intuition. 

It seems to me that the good people at Apple need to spend 
less time saying “You can’t do that” and spend more time asking, 
"Why can't you do that?” 

The file manager is another area where the Macintosh tends 
to dump problems in the user's lap. Consider the “Where is ..." 
dialog that pops up in Hypercard from time to time. Imagine how 
intimidating that must be to the neophyte, "If the computer can't 
find it, I'm sure not going to have any luck". 

À better user interface might suggest to the user that the Mac 
can search the disk on the user's behalf. It might take a while, but 
if the user doesn't have a clue as to where some file is, time really 
doesn't become an issue. 

The problem with the file manager is that it relies too heavily 
on the user. Giving control to the user is a wonderful idea. 
Nonetheless, the user should be able to delegate tasks like 
searching back to the Macintosh. 

Perhaps you need to store a preferences or help file some- 
where. If the user moves this file on you, are you supposed to pop 
a dialog asking the user to find the file for you again? Of course 
not, you're going to store the file in a folder that you're guaran- 
teed to have access to at all times. That folder is the blessed 
folder, so called because it contains the system file and startup 
application (typically the Finder). All you need is access to the 
blessed folder under program control and your problem is solved. 

Fortunately, Apple does have a champion for developers 
who would like to unload some of the file management stuff from 
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the user. Jim Friedlander has published many useful tech notes 
for developer technical services describing how to do things like 
finding that blessed folder. 

Listing 1 adds an interesting spin to this blessed folder 
business. This XCMD, called Volumes, returns a list of all 
mounted volumes. The volumes XCMD uses a handy little 
routine called pStrToField that adds a pascal format string to the 
end of a zero-terminated run of text. It's a useful way of adding 
names that you get from the toolbox which are almost always 
Pascal strings to a container that you can return to Hypercard. 

If you're building a list, terminate each item with the ^r’ 
(carriage return) character. If you are building items, then use a 
comma. If you don’t want any delimiters, then pass a 40”, 

Because pStrToField is a general purpose routine, you 
should add it to whatever library you use to store such routines. 
If you are a regular reader of this column, you know that I use a 
file called *HyperUtils.c" for such routines. 

Retrieving the list of volumes is simple. Set some index 
counter to 1. Then repeatedly call PBHGetVinfo with the follow- 
ing fields set in the parameter block: 


ioNemePtr = pointer to a string to store the name in 
ioVRefNum = -1, tell file manager to use the volume index. 


ioVol Index = your index counter. 


Keep incrementing ioVolIndex until PBHGetVInfo returns 
an error. That’s a good indication that no more volumes were 
found. 

Each time that pbHGetVInfo succeeds, the name of the 
found volume will be returned in ioNamePtr as a Pascal string. 
We tack the obligatory colon to the end of this name and then add 
the new string to the volume list that we're building in vList. 

After all is said and done, we set the last character in the 
container to 0 because Hypercard expects containers to be null 
terminated. 

Knowing the names of all mounted volumes may not seem 
useful at first blush but given a little time, I'm sure you'll find 
many interesting ways to use this XCMD. 

Once we know all the volume names on line, we can find all 
the blessed folders. A blessed folder is one that contains the 
system and startup application (usually the finder). You can find 
the blessed folder by inspection; it's the one whose folder 
contains a very small image of a Macintosh. 

Knowing the blessed folder does have applicability in very 
many cases. Perhaps your XCMD expects to store a preferences 
file in the blessed folder. At any rate, knowing how to find the 
blessed folder should be a part of every Mac programmer's 
repertoire. The XCMD in listing 2, BlessedFolder, does just that. 
It's based on tech note 44129 by Jim Friedlander. 
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Note that this time we use PBHGetvinfo with the volume а. 
reference set to 0 and the index set to -1. By passing the пате of jane 
a volume, we are telling the file manager to look up information | х Given a pascal string, append it to 
about this volume using its name rather than a reference number | * the end of the handle passed in list 
Е РЕЗЕ : S 22. to be а valid handle 
p" . ‘ . 07 length >= Ø. 
The information returned by PBHGetVinfo gets a little | x 
fuzzy here. One of the fields returned is ioVFndrInfo whichisan | * delim is some character to stick on the 
a . ЕУ i š * end of the string to delimit it. 
array of 8 ling integers. The first entry in this array is the id of the 


. . : * if you want to build a list for presentation 
blessed folder. I'm sure this array is documented somewhere in * ina field, pass ‘\r’ as the delimiter 


tech notes and if you want to further explore this information, : DN 
that's a good place to start since IM volume IV seems to gloss | , BT VOU eres be Hid Ing: tens Базага COMAS 
over this field. * A value of 0 for delim is ignored. Pass 
Once we know the directory id of the blessed folder, wecan | * 9 when you don't want a delimiter. 
h : s МА ARERR ERE ER EKER ARERR AREA EKE / 
pass it to, climbtree (published last month), to reconstruct the full ( 
pathname of this folder. Climbtree works just as well for folders long strien;/* length of input string*/ 
as it does for files. We start climbtree off with the directory id of long oldHSize; /* size of input handle*/ 
the blessed folder which was assigned to char. end. s pointer o end or data: и 
theCPB.dirInfo.ioDrDirID. Climbtree also needs a volume strlen = str[@]; /* length of string is in first byte*/ 
reference number which we pass via ioVRefNum. oldHSize = GetHandleSizeC list ); 
Climbtree requires that you declare a CInfoPBRec some- SetHandleSize( list, oldHSize + strlen ); 
where before calling it. This is because Climbtree is recursive, end = *list + oldHSize; 


and I didn't want stack space being consumed by a declaration of 


° ° . . . x . 
(ће relatively large catalog info record with each activation. If BlockMove( (char *)kstr[1] , end, strlen ); 


you're a purist, you might take your chances with the heap and 1#С delim )( 
create a nonrelocatable block in each activation. If 8K seems like " rie rin Ge 2. i AN Br 5 " 
too much stack space to you, go ahead and declare theCPB as an 2201 ы 


end = *list + oldHSize; 
automatic of climbtree. *end = delim; 


This month’s XCMDs fall into the category of “Now that I ) 
have them, what can Ido with them”. Play around fora while and 
see what you discover on your own. In the meantime, I'll be | pascal void main paramPtr ) 


cooking up some useful applications for these XCMDs. ( XCmdBlockPtr paramPtr; 
[ £9 XxXxdXxxoooeeeoecooocoooooecexr / i. wae 
/* File: Volumes.c х / chár fend: 
x х/ , 
/ | | HParamBlockRec theHPB; 
/* Return a list of all on-line*/ Handle vlist: 
/* Takes no input and returns */ char vol_Name [256]; 
/* a carrieage return delimited*/ OSErr err: 
/* list of all volumes currently */ ў 
/* оп line х/ со1оп[@] = 1; 
/* */ = (id. 
jx T colon[1] dr 
/* ©1989, Donald Koscheka %/ /*** empty is the default answer ***/ 
J*Al Rights Reserved — */ Vlist = NewHendleC @L >; 


/®*Ж^Ж®ЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖЖЖЖЖЖЖАХЖЖАЖЖЖЖЖЖЖЖ / 


/*** Search for everu volume that is on-line***/ 
index = 1; 
do( /*** Appeal to the volume manager ***/ 

/*** for the name of each volume ***/ 


Sinclude <MacTypes.h? 
Sinclude «0SUtil.h» 
Sinclude <MemoryMgr .h> 


Sinclude «FileMgr.h? "TT: А ; xxx 

Sinclude <ResourceMor .h) / DEE IS KORANO: / 

Sinclude ‹рәѕсә1.һ vol_Name[0] = 40”; 

Sinclude <hfs.h» theHPB.volumeParam.ioNamePtr = (StringPtr)vol_Name; 
Sinclude <string.h> 

Sinclude "HyperXCmd.h* theHPB.volumeParam. ioVRefNum = Cshort2-1; 


Sinclude “HyperUtils.h” 


; theHPB.volumeParam.ioVollndex= index; 
Sdefine nil OL 


err = PBHGetVInfoC &theHPB, 9); 
char colon[2] = “\p:’; 


| ; if С !err )(/** Add each Volume to List **/ 
short pStrToFieldC str, delim, list ) Concat( vol_Name, colon ); 


char *str; pStrToFieldC (char *)&vol_Name, ‘\r’, vlist ); 
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index += 1; 


)while Cerr == noErr); 


/*** once done, tack a Ø onto the end of vlist ***/ 


len = GetHandleSizeC vlist ); 
SetHandleSizeC vlist, len+1 ); 
end = *vlist + len; 

*end = 40” 


paramPtr->returnValue = vlist; 


) 
Listing 1. Volunes.c 


[ XXOOOOOOOOEOOOOROOOOEGEEGEEEEEEEXEEX EX / 
/* File: Blessed Folder.c х/ 


/* %/ 

/* Given the name of а volume */ 
/* in params[@] x/ 

/* returns the id of the */ 

/* blessed folder. x/ 

/* «/ 


/* Based on tech note #129 */ 


/* by Jim Friedlander х/ 
Г XXXXXXOOOOEEEEGEECEEEEXX XXX XXX XX XXX / 


Sinclude 
* include 
*S include 
Sinclude 
®include 
Sinclude 
Sinclude 
8include 
8 include 
Sinclude 
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«MacTypes .h> 
«0SUtil.h» 
«MemoryMgr .h> 
«FileMgr.h»? 
«ResourceMgr .h> 
«pascal .h? 
«fs.» 
<string.h> 
“Hyper XCmd .h^ 
“Hyper Utils.h’ 


Sdefine nil ØL 


cher colon[2] = “\р:*; 
pascal void mainC paramPtr ) 
XCmdBlockPtr paramPtr; 


long sid; /*** id of blessed folder ***/ 


HParamBlockRec theHPB; 


CInfoPBRec  theCPB;/**to reconstruct path name**/ 
char  vName[256]; /*** volume we're checking ***/ 


char fullPath[256]1; 
OSErr err; 


HLockC paramPtr->params[@)] ); 
ТегоТоРав( paramPtr, *(рагатРіг->рагатѕ 101), &vName ); 


HUnlock( рагәтРіг->рагатв [0 ) 


); 


/*** Given the пате о? а volume, ***/ 
/*** try to get the volume reference***/ 


/*** number bs 
theHPB . volumeParam. ioNamePtr 
theHPB . volumeParam. ioVRefNum 


= (StringPtrOvName; 
= (short); 


theHPB.volumeParam. ioVolIndex = -1; 
err = PBHGetVInfoC &theHPB, 0); 


fullPath(@] = “‹\@'/, 
if ( lerr )( 
theCPB .dirInfo. ioFDirIndex 


= =]; 


theCPB .dirInfo.ioDrDirID =theHPB .volumeParam. ioVFndrInfo(t81; 
theCPB .dirInfo. ioVRefNum= theHPB.volumeParam. ioVRefNum; 


fullPath(@] = ‘\0’; 


ClimbTreeCtheCPB .dirInfo. ioDrDir ID, 
(CInfoPBPtr &theCPB, (char *)fullPath ); 


peramPtr-»returnValue = РаѕТо2егос paramPtr, fullPath ); 


) 
Listing 2. BlessedFolder .c 


Pad! 


«ыыр» 


© The Best of MacTutor, Vol. 5 


HyperChat™ 
XCMD Corner: CopyFile 


CopyFile XCMD 

From time to time I monitor the developer forums on 
AppleLink and MacNet to see what the rest of the Macintosh 
developmentcommunity is upto. Recently, Richard Greenawalt 
of Foremost Computer Systems issued a request for some help. 
It seems he needed a routine that copies Macintosh files, data 
fork, resource fork and finder information. 

Not one to miss an opportunity to write an interesting 
XCMD, I ‘linked Rick back and told him that I would be happy 
to write the routine for him. 

The moral of the story is: ask and you might receive. If you 
need some help with an XCMD or if this column just doesn’t do 
it for you, let me know; I will be more than happy to help you out. 
Although I am up on AppleLink, I prefer to use MacNet (KOS- 
CHEKA). If you don’t have access to a modem, write me care of 
MacTutor. 

Copying a Macintosh file is not difficult as long as you keep 
in mind that Mac files are really two files in one. Each file on the 
Macintosh has a split personality - the data fork and the resource 
fork. Although the two forks act as one entity, the file manager 
treats them as separate files. 

CopyFile is a handy little XCMD that lets you copy files 
from Hypercard. Actually the routine is written to work from any 
programming milieu which is why I’ve split it into two listings. 
The first consists of the Hypercard interface. Note that you need 
to pass both the file name and the working directory id. The 
second listing contains the actual code, void of any references to 
Hypercard. This approach lets me build libraries of usable 
routines that I can use with or without Hypercard, and I intend to 
use it for all future listings. 

The CopyFile function expects to see the name of the input 
file, the name of the output file and the working directory id's of 
both. This gives you some flexibility in naming the copy as well 
as deciding what folder to put it in. For example, you can 
concatenate the name of the input file to “copy of “ so that the 
duplicated file is called “copy of file". Put this concept in a loop 
and you get the finder like capability of creating files and naming 
them “copy оѓ...“ , “copy of copy of ...” and so on. I chose not 
to implement this approach because I think the user should have 
the opportunity to specify the name of the copied file. 

Although there are several ways to go about copying a file, 
I chose a path that goes something like this: First, get the 
collective size of the data and resource fork along with the finder 
information about the input file. Using this information, attempt 
to create a file that is as large as the input file (ie as large as the 
data and resource fork combined). If the space can be allocated, 
then copy each fork in turn. If not, delete the newly created file 
and quit. 
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Space for each fork is allocated before we do the copy so that 
we can determine a priori whether the file will fit. To be safe, we 
reposition the file mark at the beginning of the file before we start 
copying. If, for any reason, the file copy fails, delete what 
remains of the file and return the error message to the caller. 

The real work is done by the function, CopyFork. This 
routine will attempt to read the entire fork into a single buffer. 
Failing that, it divides the size in half until enough memory can 
be allocated to read some of the fork. Note that copyfork attempts 
to allocate a buffer large enough to read the entire fork into 
memory. If that much memory is not available, it keeps dividing 
the original size by two until a large enough buffer can be 
allocated. 

That's file copying in a nutshell. It’s not particularly 
difficult once you realize that you're really copying two files - the 
data fork and the resource fork. I’ve tried it with files up to 4 
megabytes in size and it works fine. 


ЖЖЖЖ ARERR ХХХ ХХХ EX EX / 


/* File: FileCopy.c */ 
/* param® = file reference nun */ 
/* (file is open ) IN: х / 


/*perems(0] = name of input */ 
/*params(1] = wdid of input */ 
/*parems[2] = name of output */ 
/*params(3] = wdid of output */ 
[ EXXXXXXODOOOCOCOOOOOOOOIOOCOOECE XXE XE / 
Sinclude “Maclupes.h> 

Sinclude ‹050+11.һ 

Sinclude <MemoryMgr .h» 
Sinclude <FileMgr.h» 

Sinclude <ResourceMgr .h» 
Sinclude <pascal.h» 

Sinclude <string.h> 

Sinclude "HyperXCMO.h^ 
Sinclude "HyperUtils.h"^ 


pascal void main( paramPtr ) 
XCmdBlockPtr paramPtr; 
/^®%ЖЖЖЖЖЖЖЖЖЖЖЖЖААЖЖЖЖЖЖАЖЖАЖЖЖЖХ 
х params[0] = name of input 
ж params[ 1) wdid of input 
Ж params[2] name of output 
* perems[(3] wdid of output 
KXEXXXXEEXXXEXXXXXXtXxx*xkrxxxxxxx/ 


(OSErr err; 


short inWD; 
short outwD; 
long temp; 
Str31 errCode; 


char — inFile[256]; 

cher  outFile[256]; 

peremPtr-»returnValue = ØL; 

/*** (1) Get input parameters ***/ 

HLock( paramPtr->params[@] ); 

ZeroToPas( paremPtr, *(paramPtr->params[@]), &inFile ); 
HUnlockC paramPtr-»parems(2] ); 

inWD = CshortOparemtoNumC paramPtr, 1 ); 
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HLockC paramPtr-?params[2] ); * from the input file. 


ТегоТоРав( paramPtr, *CparamPtr->params(2]), &outFile 2); * The file will be called “copy of...” 
HUnlockC paramPtr-?params[2] 2; X Each time we create the file, first 
outWD = Cshort)paramtoNum( paramPtr, 3 2; * see if that name exists, if so, keep 
temp = Clong2CopyFileC inFile, inWD, outFile, outWD 2; * sticking "copy of^ onto the name. 
/*** Flush the output volume XX / Һ52522222222222222222422222222 4) 
err = FlushVolC ØL, Ø ); ( 
NumloStr( paramPtr, temp, &errCode ); OSErr err; 
paramPtr-?returnValue = PasToZero( paramPtr, &errCode ); OSErr егг2; 

) short inref; 

LISTING 1: CopyFile XCMD. short outref ; 

long data_eof = ØL; 

OSErr CopyForkC inref, outref, siz ) long rsrcieof = OL; 
short inref; short outref; longsiz; FInfo fndrinfo; 

/YKXX4XXXXX2XXXXXXX1XXXXXXXXXXKEK /*** (2) Determine how big the input file is xxx / 

* Given that the caller has opened 1fC Cerr = FSOpenC inFile, inWD, &inref 2) == noErr I 

* a fork and passed you the names of err = GetEOFC inref, &data eof 2; 

* the input, copy the number of bytes err = FSClose( inref 2; 

* from the input fork to the output ) 

* fork. ifc Cerr = OpenRFC inFile, inWD, &inref 2) == noErr X 

* The input mark should be set to err = GetEOFC inref, &rsrc.eof ); 

* start of fork. err = FSClose( inref ); 

* We use a "semi-smart^ algorithm 

* to do the copy. If the entire /*** (2) Create output file and allocate space***/ 

* fork can be copied, we try doing ifc C err = GetFInfoC inFile, inWD, &fndrinfo ) ) != noErr ) 

* that, otherwise, we keep dividing return( err ); 

* the size by two until we get enough ifc C err = Create( outFile, inWD, fndrinfo.fdCreator, 

* room to read some data in. fndrinfo.fdType )) != noErr ) 

ЖЖХЖЖЖЖЖЖЖЖЖЖХАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖХЖ / return( err ); 

{ /*** (3) Try to allocate enough space for both***/ 
OSErr rd.err = noErr; /*** forks. Note that if we get enough space. ***/ 
OSErr wrt err = noErr; 1f( Cerr = FSOpenC outFile, outWD, &outref )) != noErr) 
long rd_len; /*** actual bytes read ***/ return( err ); 

Ptr inbuf ; ifc Cerr = SetEOFC outref, data_eof )) != noErr X 
/*** make sure that the size is even ***/ егг2 = FSCloseC outref 2; 
ifc siz 8 2 2 err2 = FSDeleteC outFile, outWD ); 
++siz; return( err ); 
ifc siz? Ø )( 
do( егг2 = FSClose( outref ); 
inbuf = NewPtr( siz ); err = OpenRF( outFile, outWD, &outref ); 
1f( !inbuf ) 1fC Cerr = SetEOFC outref, rsrc_eof 2) != noErr X 
siz = ( siz > 1); err2 = FSClose( outref ); 
)whileC !inbuf ); err2 = FSDeleteC outFile, outWD ); 
/*** inbuf is the buffer that we ***/ return( err ); 
/*** read the data into. If not***/ 
/*** allocated, don’t attempt to do ***/ err2 = FSCloseC outref ); 
/*** the read ЗЕЯ, /*** (4) Сору the Data fork xxx / 
if inbuf )( err = FSOpen( inFile, inWD, &inref ); 
do ( VC terr )( 
rd. len = siz; err2= SetFPosC inref, fsFromStart, ØL ); 
rd err = FSRead( inref, &rd len, inbuf 2; err = CopyFork( inref, outref, data_eof ); 
wrt_err= FSWriteC outref, &rd len, inbuf ); err2= FSClose( inref 2; 
)whileC !rd.err && !wrt err ); err2= FSClose( outref ); 
DisposPtr( inbuf ); ifc err )( 


err2 = FSDeleteC outFile, outWD ); 


return( err ); 
return( wrt err ); 


) /*** (5) Now copy the resource fork — ***/ 
err = OpenRFC inFile, inWD, &inref 2); 

OSErr CopyFileC inFile, inWD, outFile, outWD ) if lerr )( 

char *inFile; err2= SetFPosC inref, fsFromStart, ØL ); 

short inWD; char ‘*outFile; err = OpenRF( outFile, outWD, &outref ); 

short outWD; err = CopyFork( inref, outref, rsrc_eof 2; 
/YSYXX35XX2XXXXXXXXX5XXXXXXXKX err2 = FSCloseC inref ); 
* (1) Determine the size of the input ) егг2 = FSCloseC outref ); 
* file. 
* (2) Attempt to allocate that ifc err )( 
* much space for the output file. err2 = FSDeleteC outFile, outWD ); 
* (3) If allocation successful, return( err ); 
* create the output file. 
* (4) Once the file is created, return( noErr ); = 
* copy the data fork, the resource ) Sol 
* fork and the finder information LISTING 2: CopyFile and CopvFork Functions. SPEEDS 
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XCMD Corner: Catalog XCMD 


Bullet Proofing 

Recently, Joe Palooka wrote to complain about a bug in the 
GetFileName XCMD that appeared in this column a few months 
back. Apparently, the xcmd bombed if you passed it more than 
four file types. But this letter raises a more important issue: how 
much bulletproofing should I do to my code examples? 

Before you jump to the obvious conclusion, allow me to 
make my case. Bulletproofing my code examples carries three 
liabilities for this column, size and clarity and time. The former 
is obvious. This magazine can carry only a certain number of 
pages per issue. Exceeding that page limit on a regular basis will 
result in my column getting bumped or serialized. I would like to 
avoid either case. 

Clarity is not so obvious and, in fact, is a function of size. 
The larger a program is, the more unreadable it becomes. Bullet- 
proofing code tends to be fairly routine, and one can almost apply 
a formula to XCMDs for bulletproofing: (1) Are the input 
parameters defined? (2) if so, are they properly conditioned (e.g. 
correct number of data). 

The final liability is time. My years of experience have 
taught me that a large amount of a programming project’s time 
is spent anticipating exceptions. Working under a monthly 
deadline, it is often necessary to eliminate this step. I don’t see 
any contradiction here. If you intend to use my code in your own 
product, then it’s incumbent on you test its effectiveness. Bullet- 
proofing my examples will only make your job harder and even 
then, I have no way of anticipating your exceptions (i.e. what 
happens to subroutine x if I make this small change to its 
parameters?) 

This code tends to take the form: 


if( paramPtr->params[i] && **CparamPtr->params(i]) )... 


Testing the input parameters is something else entirely and 
can easily exceed the size of the “functional code”. 

This is not to belittle the need for bulletproof code. Far from 
it. If you intend to use the code in this column, you should use 
it as a starting point. In general, if you intend to use somebody 
else’s code, you should seek answers to these questions: what 
does the code do? what doesn’t the code do? 


Atany rate, I will leave this issue on your hands. Write tothe | 


editor and let him know your feelings. 


Catalog 
One good XCMD deserves another. Recently, Joe Zuf- 
foletto called me to ask whether I had any intentions of writing 
an XCMD that returns a catalog of a given directory. You may 
recall that Joe gave us the series on adding standard Mac 
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windows to Hypercard. Such code cannot go unrewarded and so 
this month's xcmd ... 

Catalog accepts parameters in one of two forms. If you pass 
a pathname in the first parameter, it will return a catalog of all 
filesin that directory. Ifthe first parameter isempty, then Catalog 
will use the second parameter as directory reference number. 
This second parameter requires further explaining by way of the 
file manager. 

When the user selects a file from the standard file dialog, the 
name as well as the volume reference number is passed back to 
the caller. Under HFS, the volume reference number masquer- 
ades as a working directory id. In reality, this reference number 
acts as either a volume reference number or a working directory 
id. How the file manager tells them apart is subtle but important: 

Volume reference numbers are small negative integers such 
as -1, -2, -3... In fact, if you pass such a number to Catalog, you 
will get a listing of the root directory of the volume in question. 

Working directory id's are x. Working directories must not 
be confused with directory id's. Each file has a unique id 
assigned to it called a directory id. This id is a long integer that 
uniquely identifies a file or folder. Working directory id's by 
contrast are integers and are not unique for a given folder. 
Working directories are very much like file reference numbers. 
When a working directory is opened by the call, PBOpenWD, a 
reference number is returned in the vRefNum field. 


Listing 1: 
/Ж*ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ / 
/* File: Catalog.c */ 

/* */ 


/* Given the reference number of*/ 
/* & working directory or volume*/ 
/* return a list of all files & */ 
/* folders in that directory */ 

/* */ 

/* if a name is given, use it, */ 
/* otherwise, use the id passed*/ 
/*Ж®ЖЖХЖЖЖХЖЖАЖЖАЖЖЖЖАЖЖАЖЖААЖЖЖЖЖЖКЖ / 


Sinclude 
Sinclude 
Sinclude 
* include 
S include 
“ілсімде 
*include 
S include 
S include 
* include 


«MacTypes .h? 
‹050+11.№ 
«MemoryMgr .ћ› 
«FileMgr.h? 
«ResourceMgr .h> 
«pescal.h? 
<string.h> 
‘hfs. 

“Hyper XCnd .h^ 
"Нурегу+ ils.h^ 


"define nil ØL 


extern GetCatalog(); 
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pascal void main( peremPtr ) /*** utils.c, you can obtain it***/ 
XCmdBlockPtr paramPtr ; /*** from MacTutor for a small ***/ 


/*** handling charge ***/ 


Handle catalog; 
Str31 str; Sdefine SYNCO 
short dir ID; 
AppendCharToHandleC theHand, theChar ) 
/*** intialize the output container xxx / Handle theHand; 
catalog = NewHandle(C ØL ); char theChar ; 


[**XXXXXEXXXXEXEEDGOOOECEEEXXXX 
/*** convert the wdid to a usable form ***/ * Given a valid handle, append 
1fC peremPtr-»peremst1) X * the character passed in to 
HLockC paremPtr-»perems(1) 2; * the end of the handle 
ZeroloPas( paramPtr, *CparamPtr->params([1]), &str ); * 
HUnlock( paramPtr->params(1] ); * 


This is a useful way to embed 
dirID = (short)StrToNum( paramPtr, &str ); 


\r, M or \0 into а container 
* for use by hypercard. 


% 


/*** given the id of a directoru, x**x/ XXXXXOOOOCEECEXXOEEOECECEEEEXEEXE / 

/*** return a catalog for that directory ***/ 

GetCatalog( dirID, catalog 2; long hsiz = GetHandleSizeC theHand 2; 
) char  *dirP; 
else 1f( paramPtr-,params[0] X 

char path[256); SetHandleSize( theHand, hsiz + 1 ); 

CInfoPBRec catPB; dirP = *theHand + hsiz; 

WDPBRec wdPB; ) *dirP= theChar; 

HLockC paramPtr->params[8) ); 

ZeroToPas( paramPtr, *(paramPtr-,jparams[0)), &path 2; GetCatalog( wdref, dirH ) 

HUnlockC paramPtr-?parems[2] ); short wdref ; 


Handle dirt; 


ххх get 8 directory id to this path xxx / [FXXXXXEXXXXXXXXXXXXXXXXxxxxx 
* Get a listing of the directory 
catPB.dirInfo.ioNamePtr = CStringPtr path; * passed in. 
catPB.dirInfo.ioFDirIndex = 0; * In: 
catPB.dirInfo.ioVRefNum = 0; * wdref == reference number of the 
1f( PBGetCatInfoC &catPB, 0 ) == noErr ) * the desired working directory 
ifc catPB.dirInfo.ioFlAttrib & 0x010 X [*** * dirH == handle to the output container. 
it’s a directory ***/ * Note that we allocate all structures 
wdPB.ioNamePtr = (StringPtr path; * in the heap to minimize the impact 
wdPB.ioWDProcID = 0; * a high directory valence might have 
* on the stack. 
{fC PBOpenWD( &wdPB, Ø ) == noErr X XXXEYXXEXEYPOOODOOOOOE X GEO EX XO / 
wdPB.ioWDVRefNums catPB.dirInfo.ioVRefNum; ( 
wdPB.ioWDDirID = catPB.dirInfo.ioDrDirID; 05Егг done = 0; /* goes true when done searching */ 
GetCatalog( wdPB.ioVRefNum, catalog ); CInfoPBPtr catPB = (CInfoPBPtrONewPtr(C sizeof (CInfoPBRec)); 
PBCl1oseWD( &wdPB, 0 ); WDPBPtr wdPB = (WDPBPtrONewPtr( sizeof (WDPBRec)); 
) cher *fname = (char *)NewPtr( 256L ); 
1f( catPB && wdPB && fname X 
/*** append a null to the end of the x*x/ | catPB->dirInfo. ioNamePtr = (StringPtrj)fname; 
/*** the directory for Hypercard BER] catPB->dirInfo. ioFDirIndex = 0; 
AppendCharToHandleC catalog, “Vë 2; catPB-»dirInfo.ioVRefNum- wdref ; 
paramPtr-»returnValue = catalog; do { 
) *(catPB->dirInfo.ioNamePtr) = 70” 
catPB->dirInfo. ioFDirIndex++; 
Listing 2: catPB-»dirInfo.ioDrDirID- 0; 
Sinclude <MacTypes.h»> ifc (done = PBGetCatInfoC catPB, SYNC ) ) == noErr Í 
Sinclude ‹050+11.№ pStrToFieldC fname, '', dirH ); 
Sinclude <MemoryMor .h> 1fC catPB->dirInfo.ioFlAttrib & 0x810 X /ххж 
include <FileMgr.h> it’s a directory ***/ 
include <ResourceMgr .h? AppendCharToHandleC dirH, ':^ 2; 
Sinclude <pascal.h? ) 
Sinclude <hfs.h AppendCharToHandle( dirH, ‘\r’ ); 
Sinclude <string.h 
include “HyperXCmd.h’ )while( ‘done ); 
Sinclude “HyperUtils.h” 
DisposPtr( CPtrOcatPB ); 
/*** If you read this column ***/ DisposPtr( (Ptr )wdPB ); 
/*** column on a regular basis ***/ DisposPtrC (Ptr fname ); 
/*** you may want to add these ***/ = 
/*** routines to HyperUtils.ct*t/ ) 22) 


/*** If you don’t have Hyper-***/ 
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A Look Into Networking 


Programming the Network 

Network programming is fun. Over the past year, I’ve 
presented a suite of XCMDs that provide the Hypercard devel- 
oper with network access. Rather than present a new XCMD this 
month, I thought it might be interesting to revisit some of the 
xcmds that we developed during the year. If you don't have 
access to back issues of Mactutor, you can obtain the source code 
for these xcmds from this magazine. 

Programming the network is not unlike programming in 
Hypertalk. In both instances, you are concerned with the behav- 
ior of distributed processes. In HyperTalk, processes are distrib- 
uted over several card and background objects. On the network, 
objects are distributed over time. 

Time distribution of processes adds a new wrinkle to the 
programming task: how do you know when a given process has 
completed? The problem stems from the fact that we operate the 
network asynchronously; when we issue a request for some 
network service, we don't wait around for an answer. Rather, we 
return to Hypercard, leaving the network to handle the request in 
its own good time. 

Figure 1 depicts a card for a prototypical network applica- 
tion called Hyperserver. The card contains two icons, each of 
which provides some access to the network. Clicking on the 
volumes icon will cause the card to display a list of available 
servers. Selecting one of these servers will immediately send a 
message to the selected server requesting a list of its mounted 
volumes. Similarly, the catalog icon will return a catalog of the 
current folder on the server (for now, I leave it to your imagina- 
tion to determine what other things one can do with such a card). 


: |е Weicome to HyperADSP! 
e Call "Allen" 
e Connect To: Allen 
e Pending 


server : 
p 


catalog: 


Figure 1. A prototypical screen for HyperServer 
The process of sending a message to a server requires that 


you first call the call the server. Next you send a “get volumes” 
message to the server. Then you must wait for a response from 
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the server. Once the server responds, you hangup). 

Waiting for some input before advancing to the next stage 
suggests a state machine. Figure 2 depicts just such a state 
machine. Each circle in the diagram is a state. The double circles 
are termini. They start or begin a process. The arrows are state 
transitions, their labels tell us what stimulus will force a transition 
to the next state. The looping arrows in the diagram suggest the 
concept of waiting. For example, when a call request is made, 
you can’t immediately start talking, you have to wait for the other 
party to answer first. The process of answering the call triggers 
a transition to the connected state. Once connected, requests can 
be made to the server. Since requests imply a response, this state 
needs to wait for input before moving on. The process of 
receiving an answer to the request will trigger a transition to the 
next state (handle response). Once the request is serviced, we can 
go back to the connected state where we either wait for input and 
send another request (or hang up if that’s appropriate). 

State transitions can occur in response to one of two classes 
of stimuli: external or internal. External stimuli comprise infor- 
mation coming in over the “wire”. Examples of external stimuli 
include service requests to a server and responses coming from 
aserver. In figure 2, we model the external stimuli as the Service 
state and the Handle State. The handle state accepts the input 
from the remote end as a response to some previous request 
issued in the send state. For this reason, you should never get to 
the handle state unless you first pass through the send state. 

The respond state in Figure 2 can only be reached from the 
service state. That is, you can only respond to a stimuli given that 
arequest for service was made from aremote end. (For readabil- 
ity, not all states are depicted in the figure). 


Figure 2 The State Machine For HyperServer 


Internal stimuli are called requests. Requests are messages 
that are sent to a server. Once a request is issued, we must wait 
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for aresponse. For example, calling is an example of a message 
that request a connection with the server. 

Once the server answers the call, we can move tothe connect 
state. The connect state is implemented in the idle method of the 
stack method in listing 1. In addition to listening for external 
stimuli via ADSPListen, the idle method also manages the 
request mechanism. 

We synchronize requests using a simple queue. Requests get 
added to the end of the queue and get serviced from the start of 
the queue. The queue is stored in the global container 
"message queue". Each line in message queue corresponds to 
а message. The first line in message queue is the next message 
to service (not the current message). To execute a message, we 
first move it into the *message pending" container. Every other 
element in the queue then moves up in the line. 

The message pending item will be executed on the next 
activation of the idle method. If a message is sent that requires 
some external response, it should be followed by a “PENDING” 
message. Pending does nothing which is why it's useful as a 
blocking mechanism. The only way for the queue to advance is 
to have some method activate the NextMessage method. So 
PENDING will remain the current message in the queue until 
some external stimulus unblocks it. 

For example, to issue a call to a remote called "Allen" you 
might execute something to the effect of: 


AddMessage “Call” & quote&” Allen” & quote 
AddMessage “PENDING” 


On the next pass through the idle method, the Call message 
will be executed invoking the call method in the script. The call 
method dials up the remote end and activates nextMessage which 
advance the queue to the next message, in this case the current 
message becomes “PENDING”. 

The queue cannot be unblocked until the server answers the 
call or the call times out. When the call is answered (in 
ADSPListen), the connectionMade method is activated unblock- 
ing the “PENDING” message. 

Some messages һауе don’t care results. When we hangup on 
a remote end, we generally don’t саге to wait around to see if the 
other guy hung up. Thus the HangUp message is not followed 
by a pending message. 

As a rule, if you have a message that issues a request, you 
must follow the message with a “PENDING” message will tells 
the state machine to wait for an external stimulus before proceed- 
ing. 

Listing 1 is the stack script that implements this state 
machine plus the response handlers (not shown in Fig. 1). Before 
running the state machine, we install HyperADSP in the open- 
stack method. Similarly, we shut down HyperADSP in the 
closestack method. 

Think of the idle method as implementing the connect state 
and the rest of the script should be a little easier to read. For 
brevity, I' ve left out the methods that originate the requests, but 
they're easy enough to reconstruct (or get a copy of this month's 
disk for a demo). 
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- Following are the stack methods for opening 
- closing and listening for traffic on the 


- network 


— Due to space limitations, this stack is not 
This month’s source disk contains 
— a complete demo of this stack. 


— complete. 


on openstack 


global globalADSPData, globalSKTData, globalNBPData, 


myEnti tyName 


global HyperADSPData, adspcaller, LookupTable 
global message.queue, message_pending 


set the cursor 


put empty 
put empty 
put empty 
put empty 
put empty 


put empty 
put empty 


into 
into 
into 
into 
into 


into 
into 


to 4 

card field “current Server” 
card field “Subscribers” 
card field “Current Pathname” 
card field “Current Catalog” 
card field “log” 


message_pending 
message_queue 


if globaladspdata is empty then 
set the cursor to arrow 
edspinstall 
if the result is not empty then 
put the result 


else 


nbpOpen 
if the result is not empty then 
answer the result with “OK” 


else 


nbpRegisterName *^, “Нурегбегуег” 
log “Welcome to HyperADSP! ” 


end if 
end if 
else 


log “HyperADSP already open!” 


end if 


end openstack 


on idle 


global message_pending 


— if no message is pending, get one from the queue 
— if the queue is empty, do nothing 


if message pending is empty then NextMessage 


if message_pending is not empty then 
send message.pending 


end if 


adspListen *getTheMessage" 


pass idle 
end idle 


on getTheMessage 
global hyperadspdata, adspcaller, message-pending, incoming 


set cursor to 4 
set lockscreen to true 


put hyperadspdata into incoming 


get line 1 of incoming 
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— Notice how we “turn the messages around” here. 
— 8 put message tells us to take the incoming data 
— a get message tells us to handle an incoming request 


if word 1 of it is “put” then Receive incoming 
if word 1 of it is “get” then Handle incoming 


set lockscreen to false 
set cursor to arrow 
end gettheMessage 


on closeStack 
adspRemove 
if the result is not empty then 
answer the result with “OK” 
else 
nbpC lose 
end if 
end closestack 


- Network Callback methods. 


These methods are executed in response to 
some activity on the network 


- connectionMade : answer an incoming call 
doALookup: Update the names table 


on connect ionMade 
global adspcaller 


if edspcaller is not empty then 


— now that the connection is made, we can dismiss the 
calling 

- message from the queue: 

Log “Connect to:^"&&adspcaller 

put empty into adspcaller 


NextMessage 
end if 


end connect ionMade 


on DoALookup 


- DoALookup returns a list of names along with 
- their registered types. There is a catch 

- that we need to handle: If we want to display 
-the name without the type, we need to delete 
- the last item in the line. 

- For example: 

— Koscheka, Don, HyperServer 

needs to be reported as: 

Koscheka, Don. 


- Note that asking for item1 of the line won't 
- do since the comma is part of the registered 
- name. 


global lookupTable, currentZone 


set the cursor to 4 
put GetZoneInfo(C TRUE ) into currentZone 


put nbplookupnames( "HyperServer^, currentZone ) into 
lookupTable 
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repeat with i = 1 to the number of lines in lookupTable 
get the number of items in line i of lookupTable 
put empty into item it of line i of lookupTable 
get the number of characters in line i of lookupTable 
if character it of line i of lookupTable is 4,” then 
put empty into character it of line i of lookupTable 
end if 


put line i of lookupTable into line i of card field 
“subscribers” 
end repeat 
set the cursor to arrow 
End DoALookUp 


- Generic utilities 


— SelectLine : return the content of the line 

= Clicked in by the user (card field only) 
- isBlank: return true if the field is empty 

= or contains just white space. 

on log mess 


— the idea for a network log is borrowed 
- from Chris Allen. 


repeat while the number of chars of cd fld “Log” > 15000 
delete line 1 of cd fld “Log” 
end repeat 


put “O*&&mess&return after cd fld “log” 
end log 


Function SelectLine theField 
- select a line from the given card field 
- Accepts the short name of a card field as input 


put empty into my answer 


- When selecting a line from a field, 

- you need to take into account that the 

- field may have been scrolled. 

- To determine the number of scrolled lines 
- divide the number of scrolled pixels by the 
- number of pixels per line 


put the scroll of card field theField into box_top 
put the textheight of card field theField into tsize 
put roundC box_top/tsize ) into lineNum 


— You get a mouseup in global coordinates 
- To find the line hit, you need to convert 
- to local coordinates. 


put item 2 of the rect of card field theField into 
x.global. offset 
put item 2 of the clickloc into x. hit 


- Once you find the mousehit point, 

- convert it to a line relative to top of box. 

- This “relative line? is added to the number 

- of scrolled lines to determine the actual 

- line number (e.g. if 10 lines have been scrolled 
- then the first line in the field is 11, not 1). 


subtract x.global offset from x hit 
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add trunc( xhit/tsize) to lineNum 


- in the arithmetic, line numbers will be 
normalized to Ø rather than 1. Hypercard 
starts at line 1 so adjust the offset. 


add 1 to lineNum 
put line lineNum of card field theField into my_answer 


return my_answer 
end SelectLine 


function is_blank string 
get character 1 of string 


if it is space or it is empty or it is teb or it is return 


then 
return true 
else 
return false 
end if 
end is blank 


- Queue Management 

- These routines handle management of the message 
— queue. Excuse the logic; if Hypercard has an 
— Achille’s heel, it’s the lack of useful data 

- structures. 


— Addmessage : add a message to end of queue 
— RemoveMessage: remove a message from the queue 


on AddMessage the_memo 
global message.queue 


get the number of lines in message.queue 
put the.memo into line it*1 of message_queue 
end addMessage 


on NextMessage 


- removing а message implies that the removed 

- message get put into the message_pending container 
— This method should only be called once the pending 
— message has been serviced 


global message.queue, message.pending 

if message pending is not empty then log message_pending 
put line 1 of message.queue into message pending 

delete line 1 of message. queue 


end NextMessage 


— Eo mcn d 


— Message Management 

- These routines handle management of the possible 
messages that can be received by the network. 
all messages have the form: 


- Line 1: Message Type (token) 
Line 2: Message Sender (string) 
- Line 3..n: Message dependent data 


rr ANe—nNnnnnen nnnm m ні 


Function BuildHeader mess, name 
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put mess into line 1 of temp 
put name into line 2 of temp 
return temp 

end BuildHeader 


on call someone 

adspCall someone 

NextMessage 

— notice that this message needs to be pended also 

- The block will be cleared by the connectionMade method 
end call 


on hangup someone 
ADSPHangup someone 
NextMessage 

end hangup 


on PENDING 
- This is a “wait for completion? message. Because 
- it does nothing, it blocks the message queue until 
- some data is received. The receive method will clear 
— the pending message. Only the nextMessage method can 
- unblock the queue. Notice that nextMessage should get 
- called only after the expected data is returned. 

end PENDING 


on getcatalog server, folder 
global myEntityName 


- Client is asking for a directory of the requested 
- folder. Service the request... 


if server is not empty then 
put BuildHeader( “get catalog”, myentityname) into 
send_this_message 


put folder into line 3 of send_this_message 


ADSPTalk server, send_this_message 


end if 
Nex tMessage 
end getcatalog 


on getVolumeList server 
global myEntityName 


if server is not empty then 
put BuildHeader(^get volumes”, myEntityName ) into 
send this. message 


Log server 
log send. this. message 


edsptalk server, send this message 


end if 
NextMessage 
end getvolumeList 


- Message request methods. Requests are assembled 
- by these methods and added to the request queue 


on request. volumes 
global message.queue 


put selectlineC the short name of the target ) into the- 
Server 
if theServer is not empty then 
put theServer into card field "current server" 
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AddMessage 

AddMessage 

AddMessage 

AddMessage 

AddMessage 
end if 


“Call “&&quote& theserver&quote 
“Pending” 
*getVolumelist"&&quote&theserver&quote 
“Pending” 
“Hangup“&& quo te& theserver&quote 


end request_volumes 


on request_catalog 
global message_queue 


put card field “current server” into theServer 


if theServer 


is not empty then 


AddMessage "Call^&&quote&theserver&quote 
AddMessage “Pending” 
put quote&cd fld “current pathname“&quote into temp 


AddMessage 


*getcatalog"&&quote&theserver&quote&", “&temp 


AddMessage “Pending” 
AddMessage *Hangup^&&quote&theserver&quote 


end if 


end request catalog 


- Message response methods. These methods will 
- respond to a particular message from a remote 
- end in whatever manner is appropriate. Note 
- that responses don’t get queued, they go 

— right out on the line. 


- Response messages take the same form as request 
- messages. Notice that the response methods 

- use myentityname to tell the client which server 
- is providing the response. 


on Receive something 


- À request that was made in the past is 
- being addressed, do something with the 
- incoming data (for now, just display it)’ 


if “volume? is in line 1 of something then 
log something 


end if 


if "catalog" is in line 1 of something then 
delete line 1 of something 
put line 1 of something into cd fld "current server" 
delete line ! of something 
put something into cd fld “current catalog" 


end if 


NextMessage 

end receive something 

on Handle request 
- incoming caller is making a request, do 
- something about it 


get word 2 of line 1 of request 
put line 2 of request into to_client 


if “catalog?” is in it then 
put line З of request into of. folder 
return.catalog of folder, to client 
end if 


if “volumes” is in it then 
return.volume list to. client 
end if 
end handle 


on return_catalog folder, client 
global myEntityName 


if client is not empty then 
put BuildHeader( “put catalog”, myEntityName ) into 
the_response 


Put GetCatalog( 4”, directoryID ) into temp 
put the.response&return&temp into the.response 


ADSPTalk client, the response 


end if 
end return. catalog 


on return volume. list client 
global myentityname 


if client is not empty then 
put BuildHeader( "put volumes", myentityname )- 
into the response 


Put VolumesC) into temp 
put the.response&return&temp into the response 


ADSPTalk client, the response 


end if 
end return. volume list 


Listing 1. Stack Methods for HyperServer 
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Resource Roundup 


20 Steps to Printing Incompatibility 


20 Steps to Printing Incompatibility 

Incompatible printing code. Based on what I’ve seen, this а 
popular pastime among Macintosh software developers. 

First, some background. I'd like to apologize to MacTutor 
readers for the long delay between articles. Things were pretty 
busy in 1988 as we worked on our printer drivers, culminating in 
the January announcement at Macworld Expo of drivers we 
developed for the HP Painget and the Howtek PixelMaster. 

Foran application writer, the two drivers represent two more 
examples of output devices to be compatible with. The PaintJet 
1.0 supports 2, 8, and 256 (fixed) colors with bitmap fonts, while 
the PixelMaster 1.0 is an 8-color and 24-bit color driver with the 
Mirus/URW outline fonts. 

There are many other Chooser-level printer drivers being 
offered out there. If you count just those drivers that are sold with 
a printer (see Table 1), the number has exploded from two years 
ago, when there were two Apple printers and no third-party 
solutions. There are many more (I’ve never been able to keep up) 
independent drivers, from companies like Phoenix (née 
Softstyle) and GDT. 

Of course, it's not possible for every application to test with 
every printer driver for incompatibilities, which brings me to one 
of the main points of this article. 


Device Independence 

Many programmers think you have to know what printer 
you're sending to. Each printer has its own characteristics, the 
argument goes, and it's important to optimize for those charac- 
teristics. 

Nine times out of ten, that's plain wrong. The Macintosh 
printing architecture is designed to be device-independent, and, 
though it has its weaknesses, in that regard it is pretty successful. 

I'm certainly not part of a Thought Police that forbids you 
from such practices. It's just that one of the largest areas of 
application/printing incompatibility comes from device-depend- 
encies. 

It's particularly frustrating because these problems are 
almost always unnecessary. Perfectly good driver-independent 
solutions are available for rotated text, smoothed polygons, 
custom line layout, determining paper size, and other problems 
described later on. 

And there is no question that the problems introduced by 
such device-dependencies, on the balance, outweigh the benefits 
of same. 


Read the Documentation 
The second easy way to avoid problems is to restudy the 
documentation, beginning with the "Printing Manager" chapters 
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of Inside Macintosh. Too many people don't even understand 
these basics, as evidenced by some of the problems below. 

A sample printing loop is shown in Example 1. Using such 
aloop (or something very similar) will, unfortunately, rule out at 
least five of the incompatibility opportunities below. 

When doing your basic research, don't forget that the rules 
have changed over the years. 

There's PrGeneral functionality in Inside Macintosh, Vol- 
ume V. Among the tech notes, I'd recommend #92, 118, 125, 
149, 161 and 192 for compatibility, and #72, 73 ,91 and 95 for 
extra functionality. 

There are many applications that want to get the printing 
code to do something that is not in the published interfaces. I 
understand this problem well and am certainly sympathetic; 
perhaps three years ago I got into this debate on Usenet, arguing 
the plight of the application developer. One of the examples I 
used was for a painting program to set the Imagewriter (or other 
drivers) to "square pixels" or the equivalent. 

Unfortunately, if you're not following the documented 
interfaces, how can you pull itoff? Usually the answer is trial and 
error iteration. Itmay work with the two drivers you try, but there 
will be 10 or 20 more that do don't try, and many of these will 
break. 

Today, one of the better solutions is to provide preformatted 
stationery with configured print records for specific printer 
drivers. Another approach would be to allow the user to set a 
default print record once, and then use that print record from then 
on out. 

If you're not sure your approach is compatible, I' m sure ZZ 
orLukeattech support would be glad to offer advice on a specific 
trick or approach. As always, link to MacDTS. 


20 Easy Steps 

However, you may decide that you really want printer 
incompatibilities. Perhaps you're trying to sell a particular brand 
of printer. Or maybe you need a crisis to convince management 
to hire a large tech support staff. 

Or maybe if your sales are poor enough, your publisher will 
go bankrupt and you can reclaim your copyright to market a 
better version of your application. 

Based on Palomar'sresearch, and with assistance from other 
driver writers, we've found that such incompatibility is very easy 
for you to achieve. 

To make things more complete, I've decided to mention 
specific examples where I had them. This is not to reward these 
particular programmers or companies, but just note the ones that 
happen to be on my list. 

To my knowledge, all of these problems are known to the 
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application developer and most are either fixed in later releases, 
or in the process of being fixed. 

The list is heavily skewed to the major applications, because 
those are the ones Palomar tests with most extensively. This 
doesn’t mean that these applications are more successful in 
obtaining incompatibility; nay, we expect that there are many 
more unheralded applications on the second 50 of a top 100 list 
that are equally worthy. 

Finally, in defense of my fellow programmers, it should be 
noted that the Macintosh printer architecture has evolved in a 
somewhat ad hoc fashion since the Imagewriter was introduced 
in 1984. As such, most of the decisions listed below reflect 
reasonable guesses based on an incomplete specification; many 
would qualify as outdated assumptions more than deliberate 
perversions. 

With that, let’s get on to the list of easy incompatibilities. 


1. Assume only two printers 

Example: FullPaint 

To my knowledge, only one application checks the wDev 
field and puts up the alert “could not find the print driver.” This 
unique code looks something like this: 


if См0еу››8 == bDevLaser) 
/* print one way */ 


else if (wDev»»8 == bDevCI toh) 
| /* print another */ 


else 
| AlertCALRT_YouLoseSucka, NULL); 


However, many (usually older) applications have code that 
looks like: 


if (wDev»»8 == bDevLaser) 
( /* do nice printing */ 


else 
( /* do cruddu 144 dpi printing */ 
) 


There have been more than 20 different printer drivers 
allocated a distinct wDev value. Just because it isn't a Laser- 
Writer, doesn’t mean that it will produce cruddy output. 


2. Special case on printers 

Example: Digital Darkroom 1.0, XPress 2.0 

This is slightly more subtle than the previous approach, and 
offers many opportunities for incompatibilities: 

1. If new printers are introduced, you get lousy results with 
them. 

2. If existing drivers are improved, you get the same results 
as with the old driver. 

3. If the implementation of the driver changes, you will 
likely break if you use device-specific information (such as the 
layout of the print record). 

There is one common special casing that has produced less 
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incompatibilities than most: 


if (wDevv>)8 == bDevLaser ) 
| /* send PostScript stuff */ 


else 
| /* send QuickDraw stuff */ 


However, this will cause problems with a save-now, print- 
later utility like Glue or Орепи. 

Many, many applications go well beyond this PostScript/ 
non-PostScript distinction to achieve printing incompatibility. 
They use all sorts of intimate details about the driver, what 
comments its supports, etc., etc. In several leading applications, 
the author has gone to the trouble of building tables with device- 
specific information so all sorts of things will be handled differ- 
ently. 

As will be examined below, in most cases there are other 
ways to accomplish the same thing. For example, you can special 
case the paper size based on the wDev (incompatible) or read the 
prinfo.rPage and rPaper fields of the print record (compatible). 

For many applications, this is the preferred approach to 
printing incompatibility. I’ve picked Digital Darkroom because 
the incompatible and compatible approaches are about the same 
difficulty. 

In particular, DD has a better halftoning mechanism that it 
only makes available to the LaserWriter, LaserWriter SC, and 
GCC PLP. This means that any other high-resolution black & 
white printer is out of luck. 

One better approach would be to always make this advanced 
halftone available. A second, more restrictive approach, would 
be to pick a threshold resolution, (say 220 or 300 dpi), and if a 
PrGeneral()/getRsl call returns the maximum or device resolu- 
tion as higher than that, then make the option available. 


3. Bypass printer dialogs 

Examples: HyperCard 1.2, MPW 3.0 

This is the last of the items that every printer driver writer 
mentions. 

It is the bane of our existence, because every time we add 
functionality to a driver, the application takes it away (or makes 
it difficult to find). Many printers have a print quality selection, 
or paper feed option; some have a spool for later printing options; 
our drivers include a preview before printing options. Try 
addressing a fax without the fax dialog some time. 

HyperCard and MPW are two applications that do not show 
the job dialog for the “Print” command. 

I should also note that Word 3.0 makes it a challenge to get 
at the dialogs (something that is fixed in 4.0.) PageMaker 3.0 has 
a non-standard interface that only gives you the style (“Page 
Setup”) dialog after you select printing. 

From a personal standpoint, I find the hierarchical menus in 
Cricket Presents 2.0 to be somewhat frustrating and confusing. 
On the other hand, I’ve long bitched that MORE 1.0 should print 
bullet charts in landscape and outline views of the same docu- 
ment in portrait, so I guess Cricket has a creative (if unusual) way 
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to provide needed functionality. 


4. Spool-a-page, print-a-page 

Example: MacWrite 5.0, XPress 2.0 

Once upon a time, people tried to print large files from 
floppy-based systems. Thus, some applications would submit 
print jobs to the printer one page at a time. 

This is no longer necessary, but it does achieve incompati- 
bility by defeating the functionality of many printer drivers. As 
noted in Macintosh Technical Note #125 this is a good way, for 
example, to confuse print spoolers. 

The counter approach is for the driver to lie and always claim 
itis “draft” printing. Unfortunately, this reduces the performance 
of more normal applications, which may not be expecting to free 
much memory for draft printing. 


5. Directly change GrafPort fields 

Example: SuperPaint 1.0, FullWrite 1.0 

There are several reasons why this is a great way to achieve 
incompatibility just on general principles. 

But we found that when you supply a CGrafPort for color 
printing to an application, there are a few “bit bashers” that 
provide frequent introduction to “la bomba.” 

For example, if you directly change grafptr>bkPat (as does 
SuperPaint 1.0) then, on a CGrafPort, you are clobbering the 
cgrafptr>bkPixPat handle. If the address is weird enough, like 
OxFFFFFFFF (can you say “‘black”), you will get a bus error. 

Those GrafPort fields that are used for other fields in a 
CGrafPort include: 

portBits 

bkPat 

fillPat 

pnPat 


Change any of these directly and you’re almost certain to 
achieve that desired level of incompatibility. 

The bottom line to achieving incompatibility is to make sure 
your field manipulation will be invalid on either a GrafPort, 
Color QuickDraw CGrafPort , ог a 32-Bit QuickDraw 
CGrafPort. The 6.0 LaserWriter driver is one way to test this, as 
are various drivers from Tek, Palomar and the film recorder 
companies. 


6. Send bitmaps instead of text 

Example: CricketDraw 1.1, FreeHand 1.0, HyperCard 
1.2 

This one actually is more work than working compatibly. 
After all, the Font Manager knows how to draw text, if you just 
use DrawText() and DrawString() instead of CopyBits(). 

Also, no one is going to do this on the LaserWriter — every 
customer will notice it immediately — so you must special case 
out this approach on the LaserWriter. Thus, it’s even more work 
to do CopyBits() for just the other printers. 

My favorite example is the Cricket Expressions drivers with 
built-in URW outline fonts. Because CricketDraw sends only 
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bitmaps, those fonts are not available and you get those lovely 
low-res bitmaps. 

This опе is a real opportunity to put your worst foot forward. 
Can you imagine how lousy 72 dpi text looks on a 4,000-line film 
recorder or 300 dpi printer? Can you imagine any serious 
business professional using your application on such an output 
device? Your place in incompatibility heaven is assured. 


7. Send bitmaps instead of rotated text 

Example: MacDraw II 1.0 

In this case, it's easier to be incompatible than compatible, 
but it's not strictly necessary. 

The original designers of MacDraw (1.9) came up with a 
clever way of hiding both the bitmap and text representations of 
rotated text. This means that a smart printer driver (e.g., the 
LaserWriter) can get at the actual text and its angle, while a dumb 
printer driver (e.g., ImageWriter 2.7) will automatically print the 
bitmap representation. 

The compatible way is to use the picTextBegin and picTex- 
tEnd comments, as documented by Macintosh Technical Note 
#91. 

How does this work? You send both the bitmap and text 
representations, using an empty clipping rectangle to “hide” the 
text from any dumb printer drivers, as below: 


PicComment(picTextBegin, begh); 
PicComment(picTextCenter, ctrh); 
GetClipCsaveclip); 
ClipRectCgZeroRect); 

DrawString CtheText); 
SetClipCsaveclip); 

CopyBits( theBits); 

PicComment CpicTextBegin, NULL) 


MacDraw 1.9.5 did it this way, but the MacDraw II assumed 
that any printer that’s not a LaserWriter is brain-dead. However, 
the good folks at Claris don’t seem to appreciate incompatibili- 
ties, so it’s back to the compatible approach with MacDraw II 1.1. 


8. Smooth polygons instead of comment 

Example: FullWrite 1.0, MacDraw II 1.0 

Again, the incompatible way is much easier, but there is a 
clever MacDraw/Laser Writer convention for compatibility with 
all drivers. 

The approach is very similar to the rotated text case: you can 
provide both types of information and let the driver decide. 

One piece of information is the smoothed polygon decom- 
posed into individual line segments at a specific resolution. The 
other is the set of original inflection points, so that the polygon 
can be re-rendered at any resolution. 


9. Send bitmaps instead of objects 

Example: Excel 1.5 

The final example along these lines is sending screen- 
resolution bitmap shapes instead of their QuickDraw equiva- 
lents. 

This is a great way, for example, to avoid drawing a circle 
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marker on a line plot at the actual resolution of the printer. You 
can outputa 72 dpi bitmap instead of a 300 dpi shape, thus helping 
the user to conclude that $6,000 on a laser printer was money 
down the drain. 


10. Secretly do own line layout 

Example: ReadySetGo 4.5, PageMaker 3.0 

Some applications want to do their own line layout. There 
are certainly good reasons to do that, although I would hope 
someday to have a standard system routine to handle this the 
same way for every application and printer driver 

The incompatibility opportunity is to do your own line 
layout secretly. Don't send a picLineLayoutOff comment 
(#155), as described by Macintosh Technical Note 891. Then 
your application can fight the printer driver for control of the text 
placement. 


11. Assume paper size 

Example: PowerPoint 2.0, MacWrite 4.1 

There аге lots of assumptions thatcan be made about “paper” 
size, many of them offering incompatibilities. 

PowerPoint assumes that the top and bottom margins are the 
same, so it centers things within the imageable area. If the printer 
has alarger top or left margin, then the output will not be centered 
on the physical page. 

The original MacWrite assumed that a piece of paper could 
not be wider than, say, 8" or so. This achieves incompatibility 
many oddball choices, such as printing in landscape mode. 


12. Use large drawing coordinates 

Example: Studio Session 

QuickDraw helps with this incompatibility, since it limits 
drawing coordinates to 16 bits, or+32,767. Butit does take a little 
unusual cleverness to find this one. 

Suppose you’re drawing a horizontal line on a page of a 300 
dpi QuickDraw printer. You could draw from (72,0) to (72,576), 
say, to draw an 8" line. When scaled up to 300 dpi resolution, this 
maps to (300,0) to (300,2400). 

Of course, you could also draw the same line as (72,0) to 
(7228800). After all, everything outside the page will get 
clipped, right? 

At300 dpi, this gets scaled to (300,0) to (300,120000). Since 
16 bits won'thold the latter coordinate, you get (300,1 1072), and 
your line magically disappears! Neat, huh? 


13. Hog or fragment memory 

Example: Excel 1.5 

Excel has its own unusual memory management; others may 
also be unusual, but none so among the Top 10 best-sellers. 

The current Excel asks for a large amount of nonrelocatable 
memory, not leaving much memory available for the printer 
driver. This is the single reason many printer drivers are 
aggressive about demanding memory from an application. 

Taking lots of memory, or allocating large nonrelocatable 
blocks are reasonable ways to achieve printing incompatibility. 

At the same time, the driver may create fragmentation 
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problems for your application that also show up for incompati- 
bilities. 

If you want to be incompatible, then assume that 
SetPtrSize() will always work on a nonrelocatable block. It will 
often fail due to heap fragmentation, such as a call to MoreMas- 
ters() during printing or even an open desk accessory. 

If SetPtrSize() does fail, you could instead allocate a new 
nonrelocatable block and then BlockMove() the data over. 


14. Barf when memory stolen 

Example: Full Impact 1.0 

Nowadays, drivers that use QuickDraw imaging require lots 
of memory. At 300 dpi, a black & white 8" by 10" page requires 
879K, while 240 dpi x 8" x 10" by 24 bits of color requires 13 Mb. 
And, of course, outline fonts require lots of code, temporary 
memory and decent caches for adequate performance. 

With some the memory management scheme of some appli- 
cations, such a driver/application combinations produces won- 
derful incompatibilities. 

They may very well push your grow zone procedure and 
request more memory than currently available in the heap, 
particularly in light of item 13 above. 

For a draft-mode printer, this may come at the time of 
PrClosePage() or PrCloseDoc(). For a spool-mode printer, this 
normally comes at the time of PrPicFile(). 

Delightfully, some applications immediately panic if their 
grow zone procedure is called. Many are following the advice 
from page 64 of the first edition of How to Write Macintosh 
Software says that 

In the worst case, when your grow zone gets a memory 
request that you can't fulfill, even by eliminating the monitor 
object, you shouldforce the user to save any work in memory and 
then quit the application. 

Since Scott Knaster never articulated a goal of printing 
incompatibility, it may be assumed that this is an outdated 
approach to compatibility rather than part of a deliberate incom- 
patibility strategy. 

If you're not after incompatibility, then a reasonable algo- 
rithm to use is the following: 

1. Stash some memory for later use by the grow zone. 

2. If the grow zone is asked for memory during printing, give 
it up; if you can't satisfy the request, just say “no” (i.e., return a 
size of 0). 

3. At the end of the printing loop, try to reallocate the 
memory reserve. 

4. If you then have no reserve, complain and quit. 


15. РгОреп( at beginning of application 

Example: MacDraw 1.9.5 

This historically correct approach is now a great way to 
achieve incompatibility. In particular, it causes nifty problems 
with the Chooser and MultiFinder. 

If you're trying to be boring and compatible, then do your 
PrOpen()/PrCloseQ) around each group of printing calls, as 
shown in the example and recommended by Macintosh Techni- 
cal Note #161 . 
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16. Change print record directly 

Example: PixelPaint 1.1 

The print record structure is fairly well-documented and 
well-hacked. (Ishould know: Icontributed to the documentation 
with by March 1987 “Printer Sleuthing” article.) 

However, every driver treats these fields slightly differently, 
offering many opportunities for incompatibilities. A trick that 
will fool one driver may break another. 

The one I found most effective was in the original Pixel 
Paint, which (as with some other incompatibilities) forces print 
record values to fix one bug in one version of a printer driver. The 
end result was to prevent landscape printing for most drivers. 

Many applications obtain incompatibility by forcing paper 
sizes directly by changing the print record. This is usually quite 
effective, because you usually don’t know what you’re doing, 
and the driver won’t either. 


17, Send fake handles 

By "fake" handle, I mean a pointer to another pointer that is 
not a master pointer. 

I don’t have the specific application example in front of me, 
but this is just as useful with the Printing Manager and printer 
drivers as it is with the entire Toolbox. Such а synthetic handle 
will effectively confuse the Memory Manager if the printer driver 
should be so foolish as to pass it to the Memory Manager. 

Macintosh Technical Note #117 gives you lots of great ideas 
on how to do this and why this works. 


18. Don’t call PrPicFile 

For this one I don’t have the application either; however, it’s 
very easy to explain. 

The standard print loop includes a check for spool-mode 
printing: 


PrCloseDoc(myprport); 
if ((**ph).PrJjob.bJDocLoop == 
bSpoolLoop && PrError()== noErr) 
{  GetRidOfLotsMoreMemory(); 
PrPicFileCph, NULL, NULL, NULL, status); 
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For some reason, some applications achieve incompatibility 
by not calling PrPicFile() all the time. This is, after all, a needless 
step for the LaserWriter and other draft-mode printers. 

If you don't call PrPicFile(), then no output will be pro- 
duced; the effect can be quite mystifying and is usually good for 
one phone call per customer. 


19. Ignore printing errors 

Example: Reflections, Cricket Presents 2.0 

If you want your program to halt and crash unpredictably, 
you can just blindly ignore Memory Manager and Resource 
Manager errors. Similarly, printing incompatibility can be 
achieved by ignoring printing errors. 

There are many different places that an error can occur 
during printing, such that a compatible program would call 
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PrError() after every Printing Manager call. 
The most common errors an application will see are: 


128 iPrAbort user cancelled printing 
-27 ilOAbort cancelled after printer not responding 
-108 iMemFullErr not enough memory to print 


There are several other errors you can get. For example, 
many File Manager errors are possible while spooling to disk. 

Cricket Presents is very creative in using this to achieve 
incompatibility: it crashes if the disk fills up when spooling to 
disk. Cancelling or other errors returned by PrPicFile() are just 
fine. 

One error you probably won't see is ilOAbort, since the 
printer driver resets iIOAbort to noErr after PrPicFile(). This 
means that if you try to decode error messages before the end of 
the printing loop, you'll have the opportunity to display a few 
spurious error messages. 


20. Ignore page number selection 

Example: Persuasion 1.0 

The original Inside Macintosh explains the standard subop- 
timization for imaging only those pages that are necessary. As 
explained on page II-156, look at the page numbers in the print 
record, pass only those to the printer driver, and convince the 
driver to print all the pages you pass it. 

Almost all of the commercial applications do this. For 
example, this approach is built into MacApp. 

What are the incompatibility opportunities here? Your 
application may end up imaging 20 or 30 complex pages in order 
to print just one. Not only can you tax the patience of the poor 
saps who bought your software, but you can also fill up their hard 
disk, preventing them from running it at all if they don't own a 
brand-new 80 Mb drive. 


Credits and Disclaimer 

I'll take the blame for divulging secrets but Ican't take all the 
credit for finding problems. 

Therest of the development team at Palomar deserves credit 
for much of what we found: Neil Rhodes, Mark Anderson, 
Michael Phil Ogawa and Marshall Clow. Our testing expert, 
Julie McKeehan, found many of the problems for the first time. 

The folks at HP did a lot of pounding, too. Although full 
names are not HP policy, credit goes to Bill, Terri, Cindi, Bob, 
Robin, Dave and Marty, among others. 

There are quite a few other driver writers out there who 
helped me, but they seemed less interested than I in awarding 
examples of incompatibility, probably because some dunder- 
head managers at the various application houses won't realize 
that this whole article was a tongue-in-cheek look at a serious 
problem. Soto Scott, Mark, Jacques and Seth, thank you for your 
support — and refer any irate calls to me when this hits the stands. 


Example 1: Standard printing loop 
PrOpen(); 
err = DoPrintingCdocpr inthand); 
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PrClose(); 


OSErr DoPrinting(THPrint ph) 

{ Integer firstpage,lastpage,numpages; 
Boolean isspool; 
GrafPtr saveport; 


if C!PrJobDialog(printh)) return kDidNotPrint; 


GetPort(&savepor t); 
/* Suboptimize page nos. */ 
firstpage = (**ph).PrJob. iFstPage; 
lastpage = (**ph).PrJob.iLstPage; 
numpages = lastpage - firstpage + 1; 
/* fool printer driver */ 

(**ph) .PrJob. iFstPage 
(**ph) .PrJob. iLstPage 


= 1; 

= numpages; 

isspool = (**ph).PrJob.bJDocLoop == bSpoolLoop; 
if Cisspool) numpasses = 1 

else numpasses = (**ph).PrJob. iCopies; 


FreeUpSomeMemory( ); 
myprport = PrOpenDocCph, NULL, NULL); 
for Ссорупо= 1; copyno<numpasses; copynot*) 
for (pageno-f irstpage; 
pageno<lastpage && PrError()==noErr ; 
pageno*t*); 
( PrOpenPage(myprport, NIL); 
If (PrError() == noErr) 
DrawAPage(pageno); 
PrClosePageCmyprport); 
); /*each page*/ 
PrCloseDoc(myprport); 


/* Now print spooled document */ 
if Cisspool && РгЕггог(О-- noErr) 
(  GetRidOfLotsMoreMemoryC); 
PrPicFileCph, NULL, NULL, NULL, status); 
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); 


SetPort(saveport); 
TakeBackSomeMemory( 2; 
/* Now see if there were any errors */ 
errno = РгЕггог(); 
if C(Cerrno O noErr) && 
Cerrno € iPrAbort)) /* ignore command-period */ 
(  CallErrorHandlerCerrno); 
return errno; 


else 
return noErr; 


this driver. 


Manufacturer Printer 

Apple AppleFax 

Apple ImageWriter LQ 

Apple ImageWriter 

Apple LaserWriter II SC 

Apple LaserWritert 

GCC PLP 

GCC WriteMove 

Hewlett-Packard PaintJet 

Howtek PixelMaster 

Mirus FilmPrinter 

Presentation Tech. Montage FR1 

Tektronix 4693D 

Tektronix ColorQuick 

+ Many other PostScript@ devices are also supported by 

22) 

cid. 
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System 7.0 Detailed 

Apple Computer Inc. previewed its new System 7.0 soft- 
ware direction to an estimated 1,500 software and hardware 
developers at the Worldwide Developers’ Conference in San 
Jose on May 9, 1989. The new version represents what Apple 
calls a “feature release”, which means Apple wants all users to 
upgrade to this version. It will be compatible with all Macintosh 
computers from the Mac Plus and up, but only 68030 based 
machines or those using the 68020 with a PMMU will have 
virtual memory capability under System 7.0. This version will 
shut the door on the older Mac 128K and Mac 512K machines, 
making the Mac Plus the official bottom of the product line, if it 
isn’t already. To stay in the game, all users should plan on 
upgrading their Macs to the functionality of a Mac Plus. Beyond 
that, there is the question of whether a shop should upgrade all 
their machines to at least a 68030 based machine. Both the SE and 
the Mac II offer upgrade paths to the corresponding SE/30 and 
Mac IIx machines. 


Go Buy Some RAM 

Inaddition to having atleasta Mac Plus machine, System 7.0 
requires at least two megs of RAM to run. So plan now on 
attending a MacWorld Expo and buying more memory. Show 
prices typically run $150 per megabyte. Future Macintosh 
computers may have a ROM upgrade as well, allowing them to 
work with System 7.0 with only one meg of memory by putting 
more of System 7.0 in ROM. Both the SE/30, IIx and IIcx have 
ROM SIMM card slots to allow fora future ROM upgrade. Apple 
intends to move it's entire product line to System 7.0 so they will 
find a way to make it work as cheaply as possible for their 
production units. 


New Mac Rumors 

The Apple press release for the conference makes mention 
of the fact that "Apple expects to continue to offer an attractive 
low-end product with System 7.0." We leave it to the reader to 
guess what that means. Several comments were made that a low- 
end Macintosh is coming but itis hard to imagine what that might 
be although rumors suggest Apple has already figured out how to 
improve on the Mac IIcx and make it cheaper to build. Rumors 
have also suggested a new high-end Mac IIcx running at 25 mHz 
is due shortly. And the fact that the next Mac World Expo in San 
Francisco has been pushed back from January to next April 
suggests that Apple has some great new product to release that 
will not be ready until April. Put all this together and you can 
probably conclude the following: 


* New low-end Mac at the Boston Expo? 
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* New high-end 25 mHz Mac Псх Fourth Qtr.? 
* Lap-top Mac at the San Francisco Expo '90? 


In the next twelve months Apple will release a low-end 
Macintosh and a 25 Mhz Mac IIx of some sort. These two 
products will compliment what Apple is calling “the mid-ran ge" 
of the product line, the heart of their expected sales in the next 18 
months, the Mac IIcx and the SE/30. Then in April, figure that 
Apple will release the long-awaited lap-top Mac. But if the 
portable comes out as a wimp machine with only a 68000 in it, 
then it will bomb. It better be at least a 68020 with a PMMU or 
it won't fly. The world does not need a battery Mac. The world 
needs a moveable Mac that really does fit under an airline seat! 


Core Technologies 

The main parts of System 7.0 (read the stuff that Apple is 
committed to getting done on time) are the virtual memory, IAC, 
outline fonts and improved printing. The memory manager and 
other system software have been re-written to be 32-bit clean so 
that System 7.0 will include full 32-bit addressing. This will 
allow users to plug in 4 megabyte SIMM boards into the Mac 
motherboard for 32 megs of on-board RAM. Amazing isn't it? 
The physical memory limit will move out from the current 8 megs 
to 128 megabytes of RAM with a virtual address space of up to 
4 Gigabytes. To make sure your applications are “32-bit clean", 
see technical note #212 & 213. Basically, you don't go around the 
memory manager by manipulating handles directly or trying to 
use the top 8 bits in a handle you have assumed to be only 24 bits 
of address. 

Some of the "fixes" Apple had to do to the memory manager 
to make it 32-bit clean was to move the flag bits out of the top end 
of the master pointers, change the block header format and size, 
and change the zone header format and size. They also had to 
change the interface to the CalcCRegion in Quickdraw for 
custom controls (CDEFs), as well as clean up various OS, 
toolbox, Finder and MultiFinder problems. A lot of late-night 
soda pop didn't hurt either! 

One interesting note about System 7.0 is that Apple will no 
longer special case the operating system for Microsoft software 
that can only run in one megabyte of address space. So older 
versions of Microsoft products may stop working under System 
7.0 because the Mac will no longer check and load those products 
into the first meg of memory. The fact that Apple did this 
checking at all is a testimony of the importance of the Apple / 
Microsoft relationship when the Macintosh was first introduced. 
Obviously, Apple feels less dependent on Microsoft and is no 
longer willing to put up with their software constraints. 
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Virtual Memory 

Virtual memory will extend the system RAM to typically 
double whatever RAM memory the user has, allowing more 
practical use of smaller memory machines. This will be invisible 
to the user; he won't have to worry about configuration or 
anything, it will just happen. As mentioned before, this feature 
will only work on 68030 machines or Mac II's with a PMMU. 
The applications will “see” this memory as an extension of 
normal RAM space so no changes will be required to the 
applications to take advantage of virtual memory. Going out to 
the disk will decrease performance slightly and Apple is suggest- 
ing that a reasonable setting for the virtual memory is twice the 
RAM space to prevent a lot of disk thrashing. 

Under System 7.0, there will no longer be a Finder versus 
MultiFinder choice. MultiFinder will be “on” all the time. The 
VM model is a true demand paged (4KB) model. In a future 
system release, perhaps 8.0, it will also feature protection and a 
typical mini-computer file system and preemptive scheduler 
(i.e., true multi-tasking). Incidently, the new Finder was written 
in C++ (it works on my machine!). Apple has about 200 author- 
ized copies they are using internally, but they have not received 
the final 2.0 version from AT&T to yet make it available to 
developers. As a result, C++ is not expected to be available to 
developers outside of Apple until September. It will support 
MacApp however, when it is released. 


IAC 

Apple is finally including IAC in System 7.0. The implem- 
entation is not too unlike the one published in MacTutor last year 
by Frank Alviani and Tom Snively and Frank will have an 
expanded article on it in an up-coming issue. The main thing that 
the IAC gives you is a standard mechanism for applications to 
= pass messages back and forth. It will also support dynamic 
linking of documents witha live “copy/paste” mechanism. Apple 
will define a set of standard messages called “AppleEvents” that 
applications can use to request actions of another program, such 
as “open document”. 

To implement AppleEvents, the event manager has been 
changed to allow a high-level interface for program to program 
communications by applications. The event record data structure 
has been expanded. The mouse point has been changed to be a 
LongInt. If the what field indicates a HighLevelEvent, then 
message field and point field now indicate a class and type of 
message. New toolbox calls allow applications to post and accept 
these new "high level events" as they are called. An application 
can send messages to the Finder, for example, to print a report. 
Non-event type code (I/O drivers) can also communicate with 
applications with a low level interface to PPC services. If 
applications want to implement their own message protocol 
beyond AppleEvents, then they must register their protocol with 
DTS just as the creator tags are registered, so as to avoid mass 
confusion. 

What's That You Say? 
The key to getting application-to-application communica- 
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tions to work smoothly is that everyone must speak the same 
language and that requires that Apple setthe standard by defining 
what we all should be able to respond to. We are still waiting for 
Apple to define what is meant by “formatted text" but hopefully 
they will do a better job with IAC. The magic of the Macintosh 
was not the fact that you can cut and paste between documents, 
but rather, that Apple defined a standard TEXT and PICT data 
type that allowed multiple vendors to design tool applications 
that could read and write compatible documents. That standard 
data type needs to be extended to include formatted text and other 
data types as wellas standard commands, or AppleEvents as they 
are being called. We encourage Apple to continue to lead the way 
in defining standard data types for both text and graphics as this 
will make the design of meaningful IAC applications much 
easier. 

One of the important messages of the conference concerns 
something not officially talked about yet. Apple plans to define 
an official “Apple Script" based on HyperTalk and put it into the 
system. This will allow a common "scripting language" that any 
application can use, including the Finder. It means that develop- 
ers can add user extendibility to their applications using Apple 
Script without having to write a parser or compiler into their 
program. At least that is how I hope it will work! 


The Postscript Wars | 

Apple has declared war on Postscript with the announce 
ment that Quickdraw will continue to be the imaging engine on 
the Macintosh, and in fact, will continue to be enhanced so that 
it is better than Postscript. The first salvo from that commitment 
is the release of Quickdraw outline fonts, a Layout Manager for 
kerning, and a new printing architecture. This means that there 
will be only one type of font in the system file from now on: 
outline fonts. But they will come in two varieties: Apple outline 
fonts or Postscript outline fonts. The new printing manager will 
download both types of outline fonts to the LaserWriter so that 
the user will not need to know which type of fonts he has in his 
system file. Both will get printed at any resolution in the same 
quality. 

Outline fonts are defined by a quadratic curve and a stack 
based language instruction set. It is designed to be fast and 
flexible to allow for international extensions, and easy transla- 
tion from other font formats. And again, this cryptic remark: 
“flexible, not limited to type; designed for future System Soft- 
ware”, What does that mean? Probably tied into future Quick- 
draw enhancements somehow. 

Other technical features include projection and freedom 
vectors, automatic angle adjustment and a delta instruction for 
pixel placement at the smallest sizes. In Postscript parlance, I 
think this is called "hints". The size of the "dot" can also be 
adjusted based on the print engine being used, which is important 
for high end typesetting. Other typesetting features include a 
Line Layout Manager that draws text by using a “layout” that 
describes kerning, justification, fractional position, optical align- 
ment and other features important for easy support of non- 
Roman languages. Apple positions the Line Layout Manager in 
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quality and complexity somewhere between TeachTextand Page 
Layout, whatever that means. In addition to drawing text by 
layout, it provides for measuring the width of the line, determin- 
ing caret location, highlighting text, and testing for a mouse hit 
within the text. 

So why buy Postscript fonts anymore? From Apple’s view- 
point, you won't have to. To quote Apple's press release “...the 
Apple font format will be all most Macintosh owners really 
need." The font format has been freely distributed to font ven- 
dors, and it has been designed so that font conversion can be done 
automatically. This means font vendors can easily and cheaply 
support the new outline font technology without having to pay 
royalties. Will this break the back of Adobe and Postscript by 
providing a cheaper alternative? Could be. Think of this: Post- 
script quality laser printers at half the cost of current printers, 
using Apple outline fonts. The current crop of official postscript 
printers and imagesetters (2400 dpi machines) include a license 
cost of upwards of $1000 to include the Adobe Atlas RIP in each 
machine. That translates into a customer cost increase of $2000. 
Take that away and the same $4500 Postscript printer now costs 
$2500 and gives the same results, for fonts, that is. In particular, 
itmakes the now useless LaserWriter IISC into a very useful, and 
cheaper alternative to the LaserWriter NTX. 

Another interesting note in the Apple press release is that 
while "Apple is committed to maintaining excellent system 
support for Postscript printing", ... “our policy is to not comment 
specifically on hardware products under development." Does 
this mean a new family of Quickdraw LaserWriter printers that 
support Apple Outline fonts but does not include Postscript? 
With the future planned enhancements to Quickdraw, will such 
a family of printers end up being more powerful than today's 
Postscript printers? 


Improving Quickdraw 

The obvious difference that still remains is the fact that 
Quickdraw is not as good as Postscript at defining a graphic 
image on the page. No rotated text, for example. So whatis Apple 
doing about that? Unofficially, Apple is saying that Quickdraw 
is being re-written to be an object-oriented imaging system 
superior (and certainly faster) than Postscript. However, only 32- 
bit color and outline fonts will be ready in time for System 7.0. 
A future system release, perhaps 8.0, will include an all new 
Quickdraw imaging engine that will remove the final reasons for 
having to have Postscript at all. It will include new drawing 
primitives, floating point, 3D, animation, and possible hardware 
acceleration. The problem for Apple is, how do you extend the 
capability of Quickdraw, which is the heart of the Macintosh 
design, and not break everybody in the process? What Apple is 
saying, is that they will definitely not move to Display Postscript 
and that they definitely will upgrade Quickdraw to be at least the 
functional equivalent. 

One area Apple could quickly move ahead is in the area of 
halftones and color. Postscript does not do a good job of either. 
In releasing print driver 6.0, Apple included the ability to half- 
tone a color image on the LaserWriter. If Apple can shape it’s 
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almost fanatic interest in Multi-media presentations into the 
more mundane and practical problems of pre-press by improving 
on high-resolution typesetting, splines, halftones and color sepa- 
ration, they can continue to dominate an industry they created 
with the LaserWriter. Pre-press technology is a multi-billion 
dollar industry. By quickly adding halftones and color separation 
to low-cost imagesetters that don't include an Adobe license fee, 
technology that now costs $40,000 and up can be obtained for 
$20,000, providing another huge market for Macintosh comput- 
ers. This is where Apple could get ahead of Postscript with it's 
Quickdraw enhancements and create a justifiable reason for 
building cheaper Quickdraw based imagesetters. At the very 
least, they would be much faster, something that would not be lost 
on the growing service industry building up around Linotronic 
and other high-end imagesetters. Lets hope that in improving 
Quickdraw, Apple puts it's energy into pre-press issues like 
arbitrary text on a path, rather than the more exotic but less 
important issues like fancy animation. 


How Applications will Break 

The most radical change in System 7.0 will be in the new 
Print Manager. All current printer drivers, including the Laser- 
Writer, Linotronic, Compu-Graphic, Varityper and everything 
else out there, will be incompatible with System 7.0. Apple, will 
of course, have new printer drivers for Apple printer products, 
but what about all those expensive imagesetters out there? They 
will have to either be able to use Apple's LaserWriter driver, or 
they will have to re-write their printer driver to work with System 
7.0. And applications wanting to take advantage of System 7.0 
printing features will also have to make revisions to their dialogs. 
This one aspect of System 7.0 alone will almost guarantee every 
major software package vendor will be coming out with new 
versions to support System 7.0. 

The main feature of the new printing manager is that the silly 
thing was re-written! It was a hopeless mess of outdated code, 
exceeded only by MacInTalk in ugliness. The new manager 
offers a consistent, uniform interface for all Macintosh comput- 
ers and all printing devices, and makes printer driver writing, a 
matter of weeks, instead of months or even years, as it has been 
in the past. The intent is to allow a single image of a document on 
the screen (based on Quickdraw!) to go to any print type device 
without special casing, including a printer, another raster device, 
a vector device or whatever. Apple will provide “print engines” 
fora Quickdraw to Postscript device, Quickdraw to Raster device 
and Quickdraw to Vector device. Under this approach, plotters, 
screen capture devices and Postscript Imagesetters will all work 
the same way without changes to the application code. 

Atleast, that would be the promise if Quickdraw worked the 
way it should. You still have the problem that Quickdraw just 
can’t do some things that need to be done, so how do you get 
around that? Apple is working on trying to figure out what to do 
about PicComments and imbedded Postscript that many applica- 
tions use to extend Quickdraw's limited imaging ability. What- 
ever they come up with certainly will be designed to make future 
System expansion easier as Quickdraw evolves. One thing is for 
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sure; nearly every application will have to be modified to take 
advantage of the new system. PrOpenPage, for example, has 
been changed to PrStartPage. The format of PicComments to 
indicate the start and end of postscript has also been changed. 
PrEndPage is used instead of PrClosePage. In short, everything 
is different. Of all the parts of System 7.0, this is the one that 
scares me the most. It impacts everything, and is intimately 
connected with Quickdraw, the new outline fonts and the Layout 
Manager in it’s implementation. Let's hope they do it right. One 
advantage of the new attitude is that Apple will actually encour- 
age vendors to license the new printing driver toolkit to create 
new print drivers, even if the product competes with an Apple 
product. This should open up the creation of new peripherals for 
the Mac considerably. 


New Finder Stuff 

The Finder has been improved greatly under System 7.0. As 
wasmentioned, there willonly be MultiFinder,on allthe time. So 
plan on always using WaitNextEvent! The file organization on 
the Mac has been changed. It now uses an HFS B-Tree mecha- 
nism for improved performance. New toolbox calls are provided 
for applications to access this B-Tree capability. Searching an 80 
meg hard disk can be done quickly in 3 seconds. 

Files now have a unique FileID reference that is insensitive 
to either a folder move, or name change. This is designed to 
eliminate the infamous “lost dictionary” dialogs. A toolbox call 
resolves the FileID into the customary directory ID and File 
name. 

The Desktop file has been re-designed. It now has an entire 
Desktop Manager to manage it! This is supposed to improve 
performance on large hard disks with many files. A new File 
System Manager has been created that allows an application to 
use a foreign file system; i.e., MS/DOS. This should make it easy 
to write Mac applications that read and manage MS/DOS disks 
directly. Database access has been improved by providing a 
built-in query language called CL/1. This allows any application 
to become “data base aware” for accessing information on 
mainframe networks. 

The sound manager has been re-written to support multiple 
channels, sequencing, anew MIDI manager, and audio compres- 
sion and expansion. Kirk Austin is trying desperately to get some 
software out of Apple to give us a full report on how to plan on 
making use of all the new sound features. 


Can't Talk Yet 

One area that Apple did not improve on is MacInTalk. It 
seems that MacInTalk was a one shot deal that Steve Jobs had 
done just before the grand Mac opening in 1984. He wanted Mac 
to introduce itself" with speech. The guys who wrote it offered 
to sell the source code to Apple, but the price was too high and 
Apple refused. The result is that Apple doesn't have MacInTalk 
and never did! The fixes in version 1.31 were done by hacking the 
disassembled code to get it to run on a Mac II! One of the clear 
messages Apple got back from the conference was that people 
want an improved MacInTalk that is supported. Apple has 
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promised to provide an interim solution of a new MacInTalk that 
is slightly better, supported and runs about 100K, in the short 
term; i.e., the next twelve months. 


Tool Making Is Back! 

Finally, there are several user interface enhancements. Desk 
accessories are still supported, but now, any application can be a 
desk accessory by simply dropping it into a special Apple folder. 
So there is no reason to write a DA any more. Just write a small, 
dedicated application instead. This should give birth to a new tool 
industry on the Mac. With virtual memory, IAC and arbitrary 
desk accessories, small, powerful, single function tools are now 
the way to go in Mac software. Forget the monolithic, three years 
late, 900K integrated mega-application! Develop four well- 
connected 200K tool applications instead and drop them in the 
desk accessory folder! You can do one every six months and eat 
during your development cycle! 


Early Christmas Present 

Apple has begun releasing some of the System 7.0 goodies 
early. These include 32-Bit Quickdraw and the new LaserWriter 
6.0. The following list of files give the updated versions of the 
color quickdraw release that are different from those supplied 
with System Release 6.03, the current latest version: 

* General: 3.3.2 ° Monitors: 4.0 

• 32-bit Quickdraw: 1.0 e PrintMonitor: 1.3 

* LaserPrep: 6.0 e LaserWriter: 6.0 

If you have these versions of these files, then you have the 
new color quickdraw updates. They are further identified as 
coming from “Apple's Color Disk 1.0" in the GetInfo dialog box. 

In addition to getting “true color” for the new 24-bit color 
video boards, you also get Color Quickdraw to color PostScript 
conversion and halftoning of color images on monochrome 
Postscript printers. And the new color quickdraw includes a 
BitmapToRegion function! 

The Future 

So what can we say about the future? Get into object- 
oriented programming and MacApp! The direction Apple is 
going clearly indicates that Mac system software is converging 
with object-oriented programming and it is only a matter of time 
before the toolbox is entirely object oriented. The fact that the 
new Finder was written in C++ should be indication enough of 
the change that has taken place within Apple. MacApp is now 
being supported at the highest levels inside Apple and very soon 
we should see MacApp object support at very nearly the same 
time we get MPW Pascal and C interface support for new system 
feature releases. The latest 3.0 final version of MPW and the 2.0 
release of MacApp form the first fully functional, “finished” 
version of an object-oriented environment that MacTutor can 
encourage all developers, both Pascal and C, to get behind and 
support. For our part, we intend to devote a considerable portion 
of MacTutor editorial space to object Pascal, MacApp and C++ 
as the best way to develop Macintosh software that works with 
System 7.0 and beyond. Let us hear your comments! i 
Write me care of MacTutor and get yourself published. Se 
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Programmer's Forum 
The Installer Explored 


Steven Sheets 


The installer and Creating Scripts 

The one eternal truth about Macintosh software is that there 
will always be another System Software release. Every few 
months, swarms of Macintosh users will boot up new disks from 
Apple in order to update their machines to the latest revision. In 
the early days of Macintosh, this consisted of dragging the new 
System Folder from the new source disk to the target disk. Of 
course, any special files or resources that the user had placed in 
his System Folder would be deleted. As more Desk Accessories, 
Fonts, INITs, Printer Drivers and other non-Apple System Soft- 
ware packages were developed, the limitations of this method 
became obvious. 

Ifa user has a heavily modified System Folder, he mi ghtnot 
want to loose the special software he had installed. Reinstalling 
all the correct portions by hand (Font/DA Mover, ResEdit, etc.) 
would take time. In many cases, if someone else has modified his 
system folder for him, the user may not know how to recreate 
these changes on the new system software. 

To solve this problem, Apple introduced the Installer pro- 
gram. Most people have seen the Installer; it is included in all 
Macintosh System Software releases. By booting off the update 
disk (source) and running the Installer program, the user’s boot 
disks (target) can be updated. This update can be done file by file 
or resource by resource. Thus any special software that was on 
the target disks will not be disturbed. Fonts and Desk Accesso- 
ries will nothave to be copied over with Font/DA Mover. Special 
INITs will not have to be reinstalled. 

The Installer program is being used by non-Apple develop- 
ers as a method to install and update System Software they have 
written. With the Installer and custom made Scripts, Software 
Drivers that run special hardware are simple to install. If there are 
a number of Drivers, depending on what CPU the user has, 
multiple Scripts can becreated. Each Script would only move the 
needed files and resources to the Target disk’s System Folder. 
For example, in order to run а special INIT, an older CPU might 
require a patch that the new CPUs already have in ROM. While 
the vast majority of MacTutor readers are capable of modifying 
the System File by hand, most Mac users do not have the 
knowledge to do this. For example, by using the Installer and 
special Scripts, all the various Finder hacks can be safely done to 
a user's machine without ResEdit. 


Scripts 
The Installer program reads it's instructions from Script 
resources. These Scripts tell the Installer program what files and 
resource to copy from the Source disk's System Folder to the 
Target disk's System Folder. Script resources are of type ‘insc’. 
These Script resource must be in very specific spots in order for 
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1. The file that contains the Script must be in the System 
Folder, the same folder as the Installer program, or any subfolder 
that is in the same folder as the Installer program. 

2. Only one Script can be in any file in order for the Installer 
program to use it. As long as there is only one ‘insc’ resource, the 
ID of that resource in not important. While most Script uses ID 
0, any one will work. 

3. The Script resource must be inside a file that has a specific 
file type. Usually they are in files of type ‘uins’. A file that has 
the owner and creator of ‘uins’ will have the Installer document 
icon (ie. double clicking on that document will execute the 
Installer program). Such files are usually inside a folder called 
"Installer Scripts’ on the update disks from Apple. The Script 
resource can also be inside a file of ‘PRES’, ‘PRER’ or ‘RDEV’ 
(various Printer drivers and other Chooser devices). Thus if such 
files are in the System Folder of the Source disk, they can contain 
the instruction of how to install themselves onto the Target Disk. 
The Laserwriter Driver uses this method. 


The Script resource consists of three parts; the header 
information, the file list information and the resource file list 
information. Each part contains various data structures. Most 
data structures contain instructions for the Installer that the 
programmer must set. Other data structures are for internal use 
by the Installer and should be set to zero. A PStrisaneven padded 
Pascal String (ie. single byte count N followed by N number of 
ASCII bytes of char). A WStr is a even padded word counted 
string (ie. Integer count N followed by N number of ASCII bytes 
of char). A Word is an integer of two bytes or 16 bits, while 
LongInt is an integer of 4 bytes or 32 bits. А ResType is also 4 
bytes of data, but they are referenced as 4 ASCII characters, not 
an integer. The data structures are usually variable length; the 
Size of a structure can vary according to the content (number of 
items in list and size of strings). Knowing this, a Pascal Type 
declaration describing the Script would look somethin g like this: 


TYPE 

ScriptRec = RECORD 
Header: HeaderRec; 
FileList: FileListRec; 
ResFileList: ResFileListRec; 
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HeaderRec = RECORD 
Format: INTEGER; 
Flags: INTEGER; 
Name: PStr; 
Help: WStr; 

END; 
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FileListRec = RECORD 

NumFiles: INTEGER; 

Files: ARRAY(0..06) OF FileSpecRec; 
END; 


FileSpecRec = RECORD 
Flags: INTEGER; 
Typ: ResType; 
Creator: ResType; 
Date: LongInt; 
Hand: LongInt; 
FDelSize: LongInt, 
FAddSize:  LongInt; 
FileName: PStr; 

END; 


ResFileListRec = RECORD 

NumResFiles: INTEGER; 

ResFiles: ARRAYI2..0) OF ResFileRec; 
END; 


ResFileRec = RECORD 
TergetF ile:F ileSpecRec; 
SoureFileList: SourceFileListRec; 

END; 


SourceFileListRec = RECORD 

NumSourceF iles: INTEGER; 

SourceF ile:FileSpecRec; 

ResLists: ARRAYI2..0) OF ResListRec; 
END; 


ResListRec = RECORD 
NumResources: INTEGER; 
Resources: ARRAY(0..0] ОҒ ResSpecRec; 

ND; 

ResSpecRec = RECORD 
Flags: INTEGER; 

Typ: ResType; 
SourceID: INTEGER; 
TargetID: INTEGER; 
CRCVer: INTEGER; 
Filleri: INTEGER; 
Filler2: LongInt; 
RDelSize: LonglInt; 
RAddSize: LongInt, 
Name: PStr; 
PrevCRC: INTEGER; 

END; 


Remember that these Type declarations are not legal, but 
they are good tools to use to visualize the data structures. 


Header Information 

The header information contains the Script’s Format, Flags, 
Name and Help Message. The Format and Flags are internal 
integers and should be set to zero. The Name is a PStr containing 
the name as it will appear in the Installer program. The Name 
should include a revision number of the Script. The Help 
Message is WStr that will appear when the user presses the Help 
button in the Installer program. 


File List Information 
The File List contains the instruction about which files are to 
be manipulated (copied, deleted) from the Source Disk to the 
Target Disk. The File List starts with an integer number, 
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followed by a variable length array of File Specs. The integer is 
the number of elements of the array. Each element of the array 
contains information about each File that need to be manipulated. 

The File Spec data structure is used in the File List and the 
Resource List. It is used to pick a specific file and describe 
actions done to that file. A File Spec contains the following 
fields: Flags, Type ID, Owner ID, Date, Handle, FDelSize, 
FAddSize and Name. The Handle, FDelSize, and FAddSize are 
LongInts that are used internally and should always be set to 
Zero. If the Type ID (ResType), Owner ID (ResType) and Date 
(LongInt) are used, they should match the Type, Owner and Date 
of the Target file. If they are not used, they should be set to Zero. 
The Name is a PStr, matching the Target files name. The Flag is 
a2 byte value (16 bit) where most of the bits are Boolean flags. 
It is the Flag bits that actual tell the program what to do with the 
file. The following is their function (in least significant order). 


Bit Name Function 

0 — Setto One 

1 TypeCr: If set, the Source & Target File's Type and 
Creator must match the Date Field. If it does not 
match, the update will not be attemped. If unset, 
the Type and Creater are ignored. 

2 CrDate: If set, the Source File's Creation date must 
match the Date Field. If it does match, the 
update will not be attemped. If unset, the Date 
will be ignored. 

3 needExis:t Source File needs to exist. If it doesn't, the 
update will not be attempted. If unset, the 
Source file does not need to exist, and the Script 
will continue. 

4 DataFork: If set, when the Source file is copied to the 
Target File, the Data Fork of the Source file will 
be copied. If unset, the Data fork will not be 
copied. 

5 RsrcFork: If set, when the Source file is copied to the 
Target File, the Resource Fork of the Source file 
will be copied. If unset, the Resource fork will 
not be copied. 

6 UpdateOnly: If set and the Target file does not already 
exist, then the Source file will not be copied 
(regardless if Bit 1 is set). In that case, the 
Script will continue. 

7 Old:If set, even if TypeCR is set, Target File's Type & 
Creator need not match. The Source File's Type & 
Creator need still need to match if TypeCR is set. 

8 — Setto Zero 

9 Replace: Sorry folks, there is no documentation to 
explain this bit. However all the examples and 
sample have it turned on, and they work. So always 
set it! 

10 — Setto Zero 

11 — Setto Zero 

12 — Setto Zero 

13 Copy: If set, when the user clicks the Install button, 
the Source File will be copied to the Target File. 
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14 Dellnstall: If set and a Target file already exists, then 
that Target file will be deleted before the new 
Target File is copied from the Source Disk. 

15 DelRemove: If set and a Target file exists, when the 
user clicks the Remove button, the Target file will be 
deleted. 


Resource File List Information 

The Resource File List contains instructions about which 
resources of which files are to be manipulated (copied, deleted) 
from the Source Disk to the Target Disk. The Resource File List 
starts with an integer number, followed by a variable length 
array. The integer is the number of elements of the array. Each 
element of the array contains a Target File Spec and a Source File 
List. The Target File Spec describes which file to copy the 
resources to. The Source File List describes, file by file, the 
resources to be moved. It contains a Source File Spec (where to 
getthe resources) and a Resource List. Once again, the Resource 
List starts with an integer number, followed by a variable length 
array. Each element of the array is a Resource Spec. 

The Resource Spec contains the information describing 
exactly which resource to move. The Resource Spec contains the 
following fields: Flags, Type, Source ID, Target ID, CRC Ver- 
sion, Filerl, Filer2, RDelSize, RAddSize, Resource Name and 
Previous CRC List. Again, CRC Version, Filer1, Filer2, RDel- 
Size, RAddSize, and Previous CRC List are all used internally 
and should be set to zero. 

When a resource is moved from the Target disk to the Source 
disk, it does not need to have the same resource ID as it started 
out with. The Source ID is the resource number of the resource 
on the Source Disk. The Target ID is the resource number of the 
resource when it is moved to the Target Disk. In many cases, the 
number are the same, but they do not always have to be. The Type 
field is the resource Type of the moved resource on the Source 
Disk and the Target Disk. Thus when a resource is moved, it can 
not change types like it does IDs. The Resource Name is a PStr. 
It's usage is dependent on the Flags. Again, the Flags field is a 
group of Boolean Bit flags, whose usage is defined as: 


Bit Name Function 


0 — Setto Zero 

1 ByID: If set, find the source resource by using the 
Source ID. If unset, find the source resource by 
using the Resource Name. 

2 — Setto Zero 

3 needExist: Source Resource needs to exist. If it doesn't, 
the update will not be attempted. If unset, the 
Source Resource does not need to exist, and the 
Script will continue. 

4 EvenlfProt: If set & the Target Resource already exists, 
protecting the resource will not prevent a new 
Target Resource from being copied over it. Nor 
will it protect it from a deletion. If unset, and 
the Target is protected, the original Target 
Resource can not be deleted or copied over. In 
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that case, an update will not be attempted. 

5 — Setto Zero 

6 UpdateOnly: If set and the Target Resource does not 
exist, then the Source file will not be copied 
(regardless if Bit 1 is set). In that case, the 
Script will continue. 

7 OldName: If set, and if ByID is set, Target Resource's 
Name need not match the Resource Name. 

8 — Setto Zero 

9 — Set to Zero 

10 — Setto Zero 

11 — Set to Zero 

12 — Set to Zero 

13 Copy: If set, when the user clicks the Install button, 
the Resource in the Source File will be copied to 
the Target File. 

14 DelInstall: If set, and if a Target Resource already 
exists, then that resource is deleted before the new 
Target Resource is copied from the Source Disk. 
For most cases, this bit must be set, or else, 
when the Target Resource is copied over, two 
resources with the same number and type will 
exist in one file. Somehow the file’s resource 
map becomes corrupted. 

15 DelRemove: If set and if a Target resource exists, 
when the User clicks the Remove button, the Target 
Resource will be deleted. 


Tools 

The best tool in which to create an Installer Script is MPW’s 
Rez. While any Resource editor (ResEdit, RMaker, etc.) can 
create a Script, it is easiest to create one while using Rez. The 
various Flag bits are manipulated as Boolean values and do not 
have to be calculated into an Integer. All of the preset data 
structures (empty handles and bits) are done by Rez, and are 
invisible to the user. List Counts are calculated by Rez, as are 
word alignments. 

Rez and Derez use Include files to define the format of 
various resources. The format of a ‘insc’ type resource is 
contained in the MPW file "SysTypes.r". Any use of Rez or 
Derez must reference this file. 


Examples 

In many cases, a Script file contains only the instructions on 
how to move the resources and files from one disk’s System 
Folder to another. Those types of Script files can be in the System 
Folder or in the folder that contains the Installer program or in 
some subfolder of the folder that contains the Installer program. 
However, while many Script files contain only the instructions, 
other Script files can contain the resources that are to be moved. 
In these cases, the Script files must be in the Source disk’s System 
Folder. The Installer program can thus access the file for both 
instructions and resources. The following resource code ex- 
amples create Script files of that type. They are compiled using 
the MPW Rez tool. 

FlameTrash and NormalTrash are example of Scripts that 
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modify existing System Software. In both cases, the Script is 
designed to copy the Trash Can ICN# resources. The Flags are 
set so that resource numbers 500 & 501 in the Script file are 
copied to resource numbers 130 & 134 in the Finder file. The 
various files are found by their Name, Creator & Type. Since the 
Script was not meant for a specific revision of the Finder, the 
CrDate flag was unset and the Date field was not used. The 
resources are found by resource ID & type, so the resource name 
is not important . These Scripts have no remove feature since the 
Finder must always have the Trash Can resources. Thus to 
change the Trash Can to normal, the NormalTrash Script must be 
used. 

SampleProc is an example of how to install new resources 
and files into the System Folder. This type of Script can be used 
to install new Drivers, Fonts, or various Macintosh Procedure 
code resources like MenuProc, WindowProc, ControlProc, etc. 
SampleProc copies a dummy resource (number 0 and type 
‘XX XX’) from the Script into the System file. The Script also 
copies itself into the System Folder. Thus if the Target disk has 
the Installer program on it, it is ready to install the SampleProc 
onsome other disk. The same technique can be use to install other 
files; as an example, the Laserwriter Script installs the Laser- 
writer Prep file. In this Script, the DelRemove flag is set for the 
resource and the file, since both can be deleted without any 
problems. By pressing the Remove Button, the new SampleProc 
script is deleted and the ‘XX XX’ resource in removed from the 
System File. Even though the Script only has a Data Fork, the 
Flags DataFork and RsrcFork must both be set in the File List for 
the file to be completely deleted. Only setting one Flag means 
that only one fork is deleted; the file still exists in the directory. 


Listing: FlameTrash.r 
x 


# Flame TrachCan Installer Script Resource Code 

* Create using with command: 

я A Rez -o FlameTrash -t uins -c uins FlameTrash.r 

я To Function correctly, Place it in the System Folder of the 
" Installer Disk. 

8 Installs the Flame TrashCan into the Target Disk's Finder. 
------------------------5/ 

include “Types.r” 

include "SysTypes.r" 


resource ‘insc’ (0, “”) ( 
format? ( 

"Flame TrashCan (v1.0)*, 

"FlameTrash Script installs the Flame Trashcan into the 
Finder. ^" 

‘This Script must be in the System Folder of the Install- 
ing Disk. ” 

“It was created for MacTutor by Steve Sheets.^, 

( /* array FileList: 0 elements */ 


д 
( /* array ResFileList: 1 elements */ 
/* (1) */ 
noDelRemove, noDellnstall, noCopy, doReplace, Old, noUp- 
dateOnly, 
noRsrcFork, noDataFork, needExist, nocrDate, typeCr, 
‘FNDR’, ‘MACS’, 8x8, "Finder", 
( /* array SrcFileList: 1 elements */ 
/* (1) */ 
noDelRemove, noDellnstall, noCopy, doReplace, Old, 
noUpdateOnly, 
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) 
); 


noRsrcFork, noDataFork, needExist, nocrDate, typeCr, 


‘uins’, ‘uins’, QxQ, "FlameTresh", 


( /* array ResList: 2 elements */ 


/* [1] */ 
noDelRemove, Dellnstall, copy, doReplace, old, 
noUpdateOnly, 
noEvenIf, needExist, byID, 
'ICN"^, 500, 130, "", 
/* [2] */ 
noDelRemove, Dellnstall, copy, doReplace, old, 
noUpdateOnly, 
noEvenIf, needExist, byID, 
‘ICN’, 501, 134, *" 


) 
) 
) 


/*Flame Trash Icon */ 
resource “1СМ8” (500, *”, preload) ( 
( /* array: 2 elements */ 


) 


/* (1) */ 
ФУІР FF FF 
$^80 00 00 
%%80 ØC 00 
$?80 06 CØ 
$?80 30 OC 
$^81 82 21 
$?80 E2 АТ 
$?80 07 EQ 
/* [2] */ 

$“1F FF FF 
$^FF FF FF 
$^FF FF FF 
$^FF FF FF 
$^FF FF FF 
$"FF FF FF 
$^FF FF FF 
$^FF FF FF 


F8 20 
01 80 
01 80 
01 80 
01 80 
81 81 
01 80 
01 40 


FB 3F 
FF FF 
FF FF 
FF FF 
FF FF 
FF FF 
FF FF 


FF 7F FF FF FE 3F FF 


00 
00 
06 
06 
61 
84 
71 
01 


FF 
FF 
FF 
FF 
FF 
FF 
FF 


00 
00 
00 
60 
06 


FF 


) i 

/*Flame Full Trash Icon */ 

resource ‘ICN®’ (501, ““, preload) ( 
( /* array: 2 elements */ 


) 
); 


Listing: 


/* 


/* (1) */ 
$“1F FF FF 
$"80 1C 30 
$781 8C ЕТ 
$786 1C 18 
$798 60 03 
$^в8 60 86 
$"83 8E ВТ 
%%80 OF FO 
/* 12] */ 

$“1F FF FF 
$^FF FF FF 
$“FF FF FF 
$“FF FF FF 
ЕЕ FF FF 
$“FF FF FF 
$“FF FF FF 
$“FF FF FF 


F8 20 40 00 


01 84 
0181 
61 86 
19 88 
39 9C 
81 81 
01 40 


F8 3F 
FF FF 
FF FF 
FF FF 
FF FF 
FF FF 
FF FF 
FF TF 


16 
EÇ 
18 
C0 
10 
CT 
01 


FF 
FF 
FF 
FF 
FF 
FF 
FF 
FF 


38 
63 
ØC 
03 
aC 
EF 
80 


FF 
FF 
FF 
FF 
FF 
FF 
FF 
FF 


NoraalTrash.r 


04 
01 
01 
01 
01 
81 
01 
02 


FC 
FF 
FF 
FF 
FF 
FF 
FF 


04 
01 
81 
61 
19 
11 
01 
02 


FC 
FF 
FF 
FF 
FF 
FF 
FF 
FE 


Create using with command: 
Rez -o NormalTrash -t uins -c uins NormalTrash.r 


tt 
tt 
# To Function correctly, Place it in the System Folder of the 
tt 
tt 


Installs the Normal TrashCan into the Target Disk’s Finder. 
= ¿= —— ee ны; 


Installer Disk. 


/ 


40 00 00 02 


80 
80 
80 
80 
81 
80 
20 


TF 
FF 
FF 
FF 
FF 
FF 
FF 


40 
83 
83 
8С 
BØ 
8E 
80 
20 


TF 
FF 
FF 
FF 
FF 
FF 
FF 
3F 
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20 00 
07 00 
0С 30 
C1 83 
84 91 
39 9C 
01 80 


FF 
FF 
FF 
FF 
FF 
FF 
FF 


FF 
FF 
FF 
FF 
FF 
FF 
FF 
FF 


20 40 
1B 3C 
14 31 
30 06 
C0 03 
38 9C 
11 DE 
01 80 


FF 
FF 
FF 
FF 
FF 
FF FF 
FF FF 
FF FF 


FF 
FF 
FF 
FF 
FF 


01 
01 
01 
01 
81 
01 
04 


ҒЕ 
FF 
FF 
FF 
FF 
FF 
FF 
FC 


02 
01 
81 
11 
19 
El 
01 
04 


FE 
FF 
FF 
FF 
FF 
FF 
FF 
FC 


80 
80 
80 
80 
80 
80 
80 
IF 


FF 
FF 
FF 
FF 
FF 
FF 
FF 
IF 


80 
81 
83 
8C 
BØ 
87 
80 
IF 


FF 
FF 
FF 
FF 
FF 


FF 


FF 
IF 


00 
18 
03 
18 
81 
C4 
iF 
FF 


FF 
FF 
FF 
FF 
FF 
FF 
FF 
FF 


38 
89 
34 
60 
cø 
18 
ЗЕ 
ЕЕ 


FF 
FF 
FF 
FF 
FF 
FF 
FF 
FF 


8 Normal TrachCan Installer Script Resource Code 


00 
00 
80 
18 
41 
93 
F8 
FF 


FF 
FF 
FF 
FF 
FF 
FF 
FF 
FF 


20 
B6 
18 
06 
06 
B9 
FC 
FF 


FF 
FF 
FF 
FF 
FF 
FF 
FF 
FF 


01" 
01" 
01" 
01" 
01" 
21" 
01" 
F8", 


FF” 
FF” 
FF” 
FF” 
FF” 
FF” 
FF” 
F8" 


01" 
01" 
C 1" 
31" 
19" 
СІ" 
01" 
F8", 


FF” 
FF” 
FF” 
FF” 
FF” 
FF” 
FF” 
F8" 


#include "Types.r"^ 
"include "SysTgpes.r"^ 


resource ‘insc’ (0, “”) ( 
format® ( 
“Normal TrashCan (v1.0)", 
“NormalTrash Script installs the Normal Trashcan into the 
Finder. “ 


“This Script must be in the System Folder of the Install- 


ing Disk. ” 
“It was created for MacTutor by Steve Sheets. ", 
( /* array FileList: 0 elements */ 


( /* array ResFileList: 1 elements */ 
/* (1) */ 
noDelRemove, noDelInstall, noCopy, doReplace, Old, 
noUpdateOnly, 
noRsrcFork, noDataFork, needExist, nocrDate, typeCr, 
"FNOR^, ‘MACS’, 0х0, "Finder", 
( /* array SrcFileList: 1 elements */ 
/* (1) */ 
noDelRemove, noDelInstall, noCopy, doReplace, Old, 
noUpdateOnly, 
noRsrcFork, noDataFork, needExist, nocrDate, typeCr, 
‘uins’, ‘uins’, 8x0, "NormalTrash", 
( /* array ResList: 2 elements */ 
/* [1] */ 
noDelRemove, DelInstall, copy, doReplace, old, 
noUpdateOnly, 
noEvenIf, needExist, byID, 
“ICN®’, 500, 130, *", 
/* [2] */ 
noDelRemove, DelInstall, copy, doReplace, old, 
noUpdateOnly, 
noEvenIf, needExist, byID, 
‘ICN’, 501, 134, “” 


) 
) 
) 

); 

/*Normal Trash Icon */ 

resource ‘ICN®’ (500, *", preload) ( 

( /* array: 2 elements */ 

/* [1] */ 
$"00 07 EO 00 00 08 10 00 03 FF FF CO 04 00 00 20" 
%%07 FF FF EO 02 00 00 40 02 00 00 40 02 44 44 40" 
%%02 22 22 40 02 22 22 40 02 22 22 40 02 22 22 40" 
$"02 22 22 40 02 22 22 40 02 22 22 40 02 22 22 40" 
9702 22 22 40 02 22 22 40 02 22 22 40 02 22 22 40" 
%%02 22 22 40 02 22 22 40 02 22 22 40 02 22 22 40" 
$"02 22 22 40 02 22 22 40 02 22 22 40 02 22 22 40" 
$"02 44 44 40 02 00 00 40 02 00 00 40 03 FF FF Co", 
/* [2] */ 
$^00 07 Ей 00 00 OF FO 00 03 FF FF CO 07 FF FF Ей" 
%%07 FF FF Ей 03 FF FF CØ 03 FF FF CO 03 FF FF CO" 
%%03 FF FF CO 03 FF FF CO 03 FF FF CO 03 FF FF Сй" 
%%03 FF FF CO 03 FF FF CO 03 FF FF CO 03 FF FF CO" 
$"03 FF FF CO 03 FF FF CØ 03 FF FF CO 03 FF FF CO" 
$"03 FF FF CO 03 FF FF CÓ 03 FF FF CØ 03 FF FF CQ" 
%%03 FF FF CO 03 FF FF CO 03 FF FF CO 03 FF FF CO" 
$^03 FF FF CO 03 FF FF CØ 03 FF FF CO 03 FF FF CÓ" 


) 
); 
/*Normal Full Trash Icon*/ 
resource ‘ICN®’ (501, “”, preload) ( 
( /* array: 2 elements */ 
/* (1) */ 
$"00 07 EO 00 00 08 10 00 03 FF FF CO 04 00 00 20" 
$^03 FF FF CØ 02 00 00 40 02 00 00 40 02 10 04 40" 
$"04 22 22 20 04 22 22 20 08 44 11 10 08 44 11 10" 
$^10 88 08 88 10 88 08 88 10 88 08 88 10 88 08 88" 
$^10 88 08 88 10 88 08 88 10 88 08 88 10 88 08 88" 
%%10 88 08 88 10 88 08 88 10 88 08 88 08 44 11 10" 
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$ 08 44 11 10 04 22 22 20 04 22 22 20 04 22 22 20" 
$"02 10 00 40 02 00 00 40 02 00 00 40 01 FF FF 80", 
/* [2] */ 
$*00 07 Ей 00 00 OF FO 00 03 FF FF CO 07 FF FF EQ" 
$*03 FF FF CØ 03 FF FF CØ 03 FF FF CO 03 FF FF CO" 
%%07 FF FF Ей 07 FF FF Ей ØF FF FF FO OF FF FF FQ" 
%”ІҒ FF FF F8 IF FF FF F8 ІР FF FF F8 IF FF FF F8" 
$“1F FF FF F8 ІР FF FF F8 ІР FF FF F8 ІР FF FF F8" 
ФФІР FF FF F8 IF FF FF F8 ІР FF FF F8 OF FF FF FQ" 
$"0F FF FF FØ 07 FF ҒҒ Ей 07 FF FF EO 07 FF FF EQ" 
$"03 FF FF CØ 03 FF FF CO 03 FF FF CO 01 FF FF 80" 
); 


Listing: SampleProc.r 
/*£—— s  . .v- . 
8 SampleProc Installer Script Resource Code 
8 Create using with command: 
Rez -o SampleProc -t uins -c uins SampleProc.r 
To Function correctlu, Place it in the Sustem Folder 
of the Installer Disk 
Installs a Sample Resource into the Target Disk’s 
Sustem File. Also it copies the Script into the 
Target Disk’s System Folder so it can Install 
itself elsewhere. This Script could be used to 
install almost any type of Proc Resource, for 
example, WindowProc, MenuProc, ControlProc, etc. 
— J 
include “Types .r” 
include “SysTypes.r” 
resource ‘insc’ (0, ““) ( 
format® ( 
“SampleProc (v1.0)”, 
“For the SampleProc Script, pressing the Install Button ” 
*installs the SampleProc Resource (Type '"XXXX^, 10 0) “ 
“into the System File. It also copies the SampleProc ^ 
“Script into the System Folder. Pressing the Remove 
Button, ^ 
"deletes the Resource and the Script. This Script must * 
“be in the System Folder of the Installing Disk. It” 
“was created for MacTutor by Steve Sheets”, 
( /* array FileList: 1 elements */ 
/* (1) */ 
DelRemove, DellInstall, Copy, doReplace, Old, noUp- 
dateOnly, 
RsrcFork, DataFork, needExist, nocrDate, typeCr, 
‘uins’, ‘uins’, 8x0, "SampleProc"^ 


1$ + 1$ tt - + 3$ 3$ # 


( /* array ResFileList: 1 elements */ 
/* [1] */ 
noDelRemove, побе11п5%811, noCopy, doReplace, 014, 
noUpdateOnly, 
noRsrcFork, noDataFork, needExist, nocrDate, tgpeCr, 
‘ZSYS’, ‘MACS’, 0х0, "System", 
( /* array SrcFileList: 1 elements */ 
/* (1) */ 
noDelRemove, noDelInstall, noCopy, doReplace, Old, 
noUpdateOnly, 
noRsrcFork, noDataFork, needExist, nocrDate, typeCr, 
‘uins’, ‘uins’, 0x0, "SampleProc", 
( /* array ResList: 1 elements */ 
/* [1] */ 
DelRemove, DelInstall, copy, doReplace, old, 
noUpdateOnly, 
noEvenIf, needExist, byID, 
"XXXX^, 0, 0, "^ 


) 
) 
) 
) 

}, 
/*SampleProc Resource */ = 
data ‘XXXX’ (0) ( Sel 
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Compiler Comparisons 


Code optimization 

You will have noticed the change in the column's title: a 
recent reader survey has shown that Forth and Basic are the two 
languages that our readers would most like to see less of in 
MacTutor. That's a shame, but we're responsive (at least we 
try)... | 

So, from now on my monthly column will have a wider 
Scope. As you might have seen, I have very often used Forth as 
a vehicle to explain general concepts of Macintosh program- 
ming. Since many subscribers don't seem to be happy with Forth 
- in fact, people often have asked about things that had been 
explained in a Forth column, but they just hadn't read. The 
column about the Notification Manager in V5#6 is a good 
example: at the bottom of page 42, one of the “ideas to be written' 
was explained as: " An example that places a Notification 
Manager request in low System memory, and starts a Timer 
routine...” ; this is just the example that was іп the Forth Forum 
that covered the Notification Manager. Anyway, I'll try to use 
other vehicles to convey the message from now on. Such as 
assembly, or maybe even C. Mach2 Forth still is a very good 
assembly-language development system because of its interac- 
tivity. Of course, you cannot create complicated macros, or 
structures, and have to resort to Forth code for those purposes. I'll 
still inform you about interesting things I come across on the 
Forth scene, but this won't be an exclusive Forth column any- 
more. Emphasis will be on two things: basic system-level things 
such as drivers, trap patches, INITs, network, new managers as 
they come up; and - on the other side of the spectrum - object- 
oriented programming in C++. 

Apple will *Real Soon Now' release a C++ under MPW, and 
we'll hopefully have a pre-release by the time you read this. C++ 
isa very interesting language, much more than a simple extension 
of C; reading Stroustrup's book I got this feeling of “yes, that's 
how one should have done it in the first place’ that I had 15 years 
ago when all Iknew was Algol 60, and came across the descrip- 
tion of Algol 68. Sadly enough, Algol 68 never really caught on; 
hopefully, C++ will. The C++ column will start with the next 
issue; including program examples if we get the pre-release soon 
enough, just *dry swimming" if not. 

This month, we'll talk once more about one of my favorite 
subjects, number crunching, speed (or the lack of it), and intelli- 
gence in compilers (or the lack of it). 


A matrix multiplication routine 
Since I am doing more and more everyday computation 
(mostly Fortran) on the MacII, I' m obviously interested in a good 
optimizing compiler. Now, a standard trick that every decent 
compiler should have in its repertoire is the elimination of 
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constantexpressions from loops, or assignment of array elements 
that are not dependent on the loop index to intermediate vari- 
ables. 

Imagine my surprise when I found out that (in Language 
Systems Fortran 1.2.1) I could speed up a loop that looked like 
this: 


by simply writing: 


do k=1,n3 

do i=1,n1 
sum = 0х0 
do j=1,n2 

sum = sumta(i,j)*b(j,k) 

end do 
c(i,k) = sum 

end do 


end do 


Now, in undergraduate programming classes, years ago, we 
were actually taught to look for constant arithmetical or index 
expressions in loops and put them outside if possible. Today, 
almost everybody assumes that the compiler is smart enough to 
take care of that; incorrectly, as you see. To see how good the 
compilers available under MPW can do, I wrote a Fortran 
program (listing 1) that calls several versions of this matrix 
multiplication loop, written in Fortran (Lang. Sys. 1.2.1), Pascal 
(Apple 3.0 beta), and C (Apple 3.0 beta). Surprise: none of the 
compilers was good enough to move the indexing outside of the 
loop. The following table gives the results (Mac IIx): 


Pascal, hand-optimized: 2.7667 seconds 

C, register variables, hand-opt.: 3.4667 seconds 
Pascal: 4.0333 seconds 

Fortran, const. dimensions, opt=3: 4.5000 seconds 
Fortran, hand-optimized, opt=3: 4.6500 seconds 
C: 4.7167 seconds 

Fortran, opt=3: 6.5167 seconds 

Fortran, opt=0: 6.6167 seconds 


A difference of more than a factor of 2 between the slowest 


Fortran and the fastest Pascal code. Apple Pascal lived up to its 
good reputation here, but even that could be improved a lot by 
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eliminating the constant index expression. 

Surprised, Iran the Fortran benchmark on a Microvax II, and 
found that even there some speed could be gained by ‘hand- 
optimizing' the code: 


Fortran, plain: 3.6333 seconds 
Fortran, hand-opt.: 3.2833 seconds 
Fortran, const. dimensions: 3.1000 seconds 


However, the difference between the machine-optimized 
and the hand-optimized version is not quite as big as for the MPW 
languages (15% for the VAX vs. 27-30% for MPW). If you 
compile the VAX code without optimization, you get a bigger 
difference (23%): 


Fortran, plain: 6.2500 seconds 
Fortran, hand-opt.: 4.8833 seconds 
Fortran, const. dimensions: 4.8000 seconds 


Therefore, take-home lesson one: don’t take compiler op- 
timizations for granted. 


The machine code behind it 

Benchmarks have been run on lots of different machines, 
using lots of different compilers. I was interested inhow the code 
generated by the MPW compilers actually differed. A job for 
Nosy, and the results are shown in the last listing. I’ve only 
printed the innermost loops. Don’t be overwhelmed by the pile 
of assembly code, just note some important details. 

First, for the loop optimization examples discussed here, 
there seems to be no tradeoff between code length and speed. On 
the contrary, the fastest code is also the shortest. On the other 
hand, there are some obvious pieces of code which are Clearly 
redundant. The most blatant example is the Fortran-generated 
code at the end of the listing, where an index expression is 
recalculated that was actually in register A 1 all the time! 14 extra 
lines of machine code on each pass through the loop will add up 
to quite some extra time lost. Another point is that Language 
System obviously has no great trust in the quality of the 68000/ 
20/30, otherwise how can one explain that they repeat the EXT.L 
D2 instruction each time it occurs? To make sure it works at least 
once? 

Language Systems Fortran makes other funny assumptions 
about the machine, for instance it seems to think there are only 
two floating point registers in the 68881, FPO and FP7. I have 
looked at some code which had great potential for optimization 
by using enough FP registers. Language Systems is, however, 
known for its responsiveness towards customers, so I hope we 
won't have to wait too long until a well-optimized Fortran shows 
up. 

Both Pascal and C like juggling floating pointregisters. Why 
generate (like Apple’s C): 


FMOVE — FP7,FP1 
FADD ‘FP, FP 
FMOVE FP 1,FP7 


when a simple FADD FPO,FP7 would suffice? Eliminates 
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two floating point instructions per loop. Pascal does 
FADD ЕРТ,ҒР@ 
FMOVE FPØ,FP7 
when a simple inversion of the operands 
FADD FP@,FP7 
would give the same result. One floating point instruction 
per loop eliminated. The timing difference between the Pascal 
and C routines is partly because of the one extra floating point 
instruction. 
Lastremark: I haven’t seen the Absoft MPW 3.0 Fortran yet. 
If anyone from Absoft is reading this, I' d like an evaluation copy 
to run the same analysis (since you claim in your ads you have 
such a great optimizer). If I get enough other languages collected 
together, we'll have a follow-up on this article. 


Next month 
The MacHack is over (thanks, Aimée, Carol, and all the 
others, for organizing such a good meeting), and T'll tell you some 
of my impressions іп the next column. Otherwise, we'll start with 
an introduction to C++; I hope the compiler will arrive here in 
time. 


Listing 1: Matrix aultiplication benchmark 


115 Main 
program matrix 
с 
c Main program in Language Sustems Fortran 


с 
с Some line breaks іп the Fortran program are due to 
c editing. 
с 
implicit none 


integer i,j,ticks1,ticks2 
extended a(50,50), b(50,50), с(50,50) 
extended time1,time2 


integer ticks 


type *, Matrix multiplication benchmark ’ 
Upe T, Se’ 
tupe * 
type ©, This program compares the number crunching power’ 
type ©, ‘of some of the popular MPW compilers. ’ 
type *, Written under MPW 3.0 by J. Langowski / MacTutor 
1980" 
type * 
type *, Setting up 50х50 matrices...’ 


ticks1 = ticks() 


do 121,50 
do j=1,50 
aci,j) = Ci- D + J-1 
bCj, 12 = aCi, j) 
end do 
end do 


ticks2 = ticks() . 

timel = (ticks2-ticks1)/60. 

tupe * 

write (6,'(f18.4,"^ seconds for setting up matrices’’)’) 
timel 


ticks1 = ticks() 
call nat mult. for3(c,50,8,50,b,50,50,50,50) 
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ticks2 = ticks() 

timel = (ticks2-ticks1)/60. 

tupe * 

write (6, (f8.4,” seconds for multiplying matrices’ ’ 
ж”” using FORTRAN routine, opt=3'’)’) time! 

type *, ’c(25,25) = ',c(25,25) 


ticks! = ticks) 
call паї mult. for(c,50,8,50,b,50,50,50,50) 


ticks2 = ticks() 

timel = (ticks2-ticks1)/60. 

type * 

write (6, ’(f8.4,’’ seconds for multiplying matrices’ ’ 
ж, 44 using FORTRAN routine, орї=0' 727) timel 

type *, ’c(25,25) = ”,с(25,25) 


ticks! = ticks) 
call mat_mult_for 1(c,50,8,50,b,50,50,50,50) 


ticks2 = ticks() 
timel = Cticks2-ticks12/60. 
type * 
write (6, ’(f8.4,’’ seconds for multiplying matrices’ ’ 
кое Using FORTRAN routine, hand-optimized’’)’) time ! 
type х, ’c(25,25) = °,c(25, 25) 


ticks1 = ticks) 
call паї ти1%4. Ғог0(с,50,а,50,0,50,50,50,50) 


ticks2 = ticks() 
timel = (ticks2-ticks1)/60. 
tupe * 
write (6, ”(f8.4,” seconds for multiplying matrices” ° 
mt using FORTRAN routine, constant dimensions’ ’)’ ) tinel 


type *, ’c(25,25) = ' ,c(25,25) 
ticks] = ticks() 
call 


mat_mu1_pas(c,$va1(50),a,$va1(50),b,$va1(50),$va1(50),$va1(50),$va1(50)2) 


ticks2 = ticks() 
timel = (ticks2-ticks1)/60. 
tupe * 


write (6,^(f8.4, ^^ seconds for multiplying matrices’ ’ 
Е using PASCAL routine’’)’) time! 
type *,'c(25,25) = °,c(25, 25) 


ticks! = 
call 
nat mul. pas opt(c, 8val (58), a, 8val(58),b, val (58), %va1 (58), val C30), %val(58)) 


ticks() 


ticks2 = ticks() 

time! = (ticks2-ticks1)/60. 

type * 

write (6, ‘(f8.4,’’ seconds for multiplying matrices’ ’ 
Worm using PASCAL routine, hand-optimized’’)’) tinel 

type *,’c(25,25) = ',с(25,25) 


ticks1 = ticks() 
call 
mat-mul_c(c,%val(5Ø),a,%val(50),b,%val(50),%va1 (58), gval(50),%val(50)) 


ticks2 = ticks() 

timel = (ticks2-ticks1)/60. 

tupe * 

write (6,^(f8.4, ^^ seconds for multiplying matrices’ ’ 
* using Ç routine”) ) time! 

type *,'c(25,25) = ',c(25,25) 


ticks] = ticks() 
call 


matunul_c_opt(c, 8va1(50), a, val(58),b, Sva 1092), val (50), $va1(50),Sva1C902) 
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ticks2 = ticksC 

tinel = Cticks2-ticks1)/60. 

type * 

write (6, (18.4, ^^ seconds for multiplying matrices” ’ 
0 using C routine, hand-optimized’’)’) timel 

type *, ’c(25,25) = ',c(25,25) 


end 


115 Main 

subroutine mat mult. for3Cc,nc,8,n8,b,nb,n1,n2,n3) 
sets c=a.b 

na,nb,nc are first dimensions 

nl n2 n3 are problem dimensions 

c is nixn3 

8 ni n2 

b n2 n3 

implicit none 


000000 


integer n&,nb,nc,n1,n2,n3 
integer*2 i,j,k 
extended c(nc,n32,8Cna,n22,bCnb,n3) 


do k=1,n3 
do i21,nl 
c(i,k) = 0х0 
do j= 1,n2 
c(i, k) = c(i, k)+aCi, j)*bCj,k) 
end do 
end do 
end do 
return 
end 


115 Main 
subroutine mat. mult. for 1(c,nc,a,na,b,nb,n1,n2,n3) 
с 
с вате as before, invariant matrix element eliminated from 
1oop 
с 


implicit none 


integer na,nb,nc,n1,n2,n3 

integer*2 i,j,k 

extended c(nc,n3),a(na,n2),b(nb,n3) 
extended sum 


do k=1,n3 
do i=1,n1 
sum = 0х0 
do ј=1,п2 
sum = sumtaCi, j2*bCj, k2 
end do 
cCi,k) = sum 
end do 
end do 
return 
end 


115 Main 
subroutine mat. mult. forQ(c,nc,8,na,b,nb,n1,n2,n3) 
с 
с same as before, with constant dimensions 
с 
implicit поле 


integer na,nb,nc,n1,n2,n3 

integer*2 i,j,k 

extended с(50,50),а(50,50),6С50,50) 
extended sum 


do k=1,n3 


do i21,nl 
sum = 0x0 
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do j=1,n2 
sum = sumta(i,j)*b(j,k) 
end do 
c(i,k) = sum 
end do 

end do 
return 
end 


115 Main 
integer function ticks 
ticks = long(362) 
return 
end 


Listing 2 : non-optimized Fortran routine 
115 Main 
Subroutine mat. mult. for(c,nc,a,na,b,nb,n1,n2,n3) 
с 
с duplicate of mat_mul_for3 for compiling without optimization 
с 
implicit none 


integer na,nb,nc,n1,n2,n3 
integer*2 i,j,k 
extended c(nc,n3),a(na,n2),b(nb,n3) 


do k=1,n3 
do i=1,n1 
cCi,k) = 0x0 
do j=1,n2 
cCi,k) = cCi,k)+aCi, j)*bCj,k) 
end do 
end do 
end do 
return 
end 


Listing 3 : Pascal routine 


($S Main) 
($R-) 
unit matmul; 


interface 


type matrix = array [1..50,1..50]of extended; 
procedure mat_mul_pas 
(var c : matrix; nc : longint; 
var а : matrix; па : longint; 
var b : matrix; nb : longint; 
n1,n2,n3:longint); 


procedure mat. mul. pas. opt 
(var c : matrix; nc : longint; 
var 8 : matrix, na : longint; 
var b : matrix; nb : longint; 
n1,n2,n3:longint2; 


implementation 


procedure mat mul. pas; 
var 
1,j,k: integer; 
begin 
for k:=1 to n3 do 
for i:=1 to nl do 
begin 
cli,k] := Ø; 
for j:=1 to n2 do 
cli,k] := cli,k]+ali, j]*blj,k); 
end ; 
end ; 
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procedure mat_mul_pas_opt; 

var 
i,j,k: integer; sum:extended; 
in 


for k:=1 to n3 do 
for i:=1 to n1 do 
begin 
sum := 0; 
for j:=1 to n2 do 
sum := sumta[li,j]*b[j,k]; 
cli,k] := sum; 


end ; i 
end . 
Listing 4 : C routine 


pascal void mat mul.c 
(extended c[50][], long nc, 
extended а(50111, long na, 
extended 5150111, long nb, 
long nl, long n2, long n3) 


int i,j,k; 


for С k=1 ; k <= n3; k++ ) 
for ( i=1; i (= nl; ін) 


clillk] = 0.0; 
for С j=1; j (= n2; jtt) 
cli][k] = clillk]+alillj]*b(j)(k]; 


) 


pascal void mat_mul_c_opt 
(extended c[501[]), long nc, 
extended a[50][], long na, 
extended 0150111, long nb, 
long nl, long n2, long n3) 


( 
register int i,j,k; 
register extended sum; 


for С k=1 ; k <= n3; кн) 
i=l 5 i (nl; i++) 


j = п; jtt ) 
mta[i]lj]*b[jl[k]; 
sun; 


— ti, © 
" 
нез 
` 


SU 


Listing 5 : inner loops compared, 
Nosy-disassemb led 


pascal, optimized 
lan-3 MOVEA.L param2(A6), Ad 
MOVE 06,00 
MULS 8%258 00 
МОУЕ 05,01 
MULS #12,D1 
ADD 01,00 
MOVEA.L param3(A6),A1 
MOVE D5,D1 
MULS #$258, D1 
MOVE 07,02 
MULS 8 12,02 
ADD D2,01 
LEA -$264(A0),A0 
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FMOVE.X @(A0,D0.W),FP0 
LEA -$264(A1),A0 

FMUL.X @(A0,D1.W),FP0 
FADD ЕРТ,ЕРО ; could use 


FMOVE FP9,FP7 ; FADD FPØ,FP7 here 


ADDQ #1,05 
BVS.S land 

lan-4 CMP.W van.1(A62,D5 
BLE lan-3 


c, optimized 
lar_1 MOVE.L 07,00 
MOVE.L 00,01 
MULU # 12,00 
SWAP D1 
MULU * 12,01 
SWAP D1 
CLR 01 
ADD.L 01,00 
ADD.L 06,00 
MOVE.L D5,D1 
MOVE.L D1,02 
MULU # 12,01 
SWAP D2 
MULU 812,02 
SWAP 02 
CLR 02 
ADD.L 02,01 
ADD.L 07,01 
FMOVE.X @(A3,D0.L),FP0 
FMUL.X 0@(A4,D1.L),FP0 
FMOVE ЕРТ,ЕРІ 
FADD ЕРЙ,ЕР1 
FMOVE FP1,FP7 
ADDQ.L 81,D7 
lar_2 CMP.L D7,D4 
BGE 1аг_1 


pascal, plain 


lam.3 MOVEA.L param2(A6),A0 


MOVE 06,00 
MULS 8%258,00 
MOVE D5,D1 
MULS #12,D1 
ADD 01,00 
MOVEA.L param3(A6),A1 
MOVE D5,01 
MULS #$258 , D 1 
MOVE 07,02 
MULS # 12,02 
ADD D2,D1 
LEA -$264CA02, Ad 
FMOVE.X @CA0,D0.W),FP0 
LEA -$264(A1),A0 
FMUL.X 0CA®,D1.W), FPO 
MOVE 06,00 
MULS #$258,00 
MOVE 07,01 
MULS #12,D1 
ADD D1,DØ 
LEA -$264(A4), Að 
FADD.X 0(А0,00.42,ҒР0 
MOVE 06,00 
MULS 8%258,00 
MOVE D7,D1 
MULS #12,D1 
ADD 01,00 
LEA -$264(A4), Að 
FMOVE.X FP0,0CA0,D0.W) 
ADDQ 81,05 
BVS.S 1ат_5 

lam.4 CMP.W уат. 1(А62,05 
BLE 18m.3 
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c, plain 
180.3 MOVE.L 05,00 
MOVE.L 00,01 
MULU # 12,00 
SWAP D1 
MULU * 12,01 
SWAP D1 
CLR 01 
ADD.L 01,00 
ADD.L D6,D0 
MOVE.L 07,01 
MOVE.L D1,D2 
MULU 812,01 
SWAP D2 
MULU 8 12,02 
SWAP D2 
CLR D2 
ADD.L 02,01 
ADD.L 06,01 
MOVEA.L param3CA6), Ad 
MOVE.L D5,D2 
MOVE.L 02,03 
MULU # 12,02 
SWAP D3 
MULU 8 12,03 
SWAP D3 
CLR D3 
ADD.L D3,D2 
ADD.L 07,02 
FMOVE.X @(A4,D1.L),FP0 
FMUL.X @(A0,D2.L),FP0 
FADD.X @(A3,D0.L),FP0 
MOVE.L 05,00 
MOVE.L 00,01 
MULU # 12,09 
SWAP D1 
MULU 812,01 
SWAP D1 
CLR D1 
ADD.L D1,D0 
ADD.L 06,00 
FMOVE.X  FP2,0CA3,D0.L) 
ADDQ.L 81,07 
180-4 CMP.L 07,04 
BGE 180.3 


Fortran, optimized 
1әһ 3 MOVE -172(A62,D2 
EXT.L D2 
EXT.L D2 
SUB.L -142(462,02 
MULS.L 812,02 
MOVE.L 02,00 
MOVE - 178CA6), D2 
EXT.L D2 
EXT.L D2 
SUB.L -130(A62,D2 
MULS.L -134CA62,D2 
ADD.L D0,D2 
MOVEA.L 32(A62,A0 
ADDA.L D2,A0 
FMOVE.X (A0),FPT 
MOVE - 170(А62,02 
EXT.L D2 
EXT.L D2 
SUB.L -118(A62,D2 
MULS.L 812,02 
MOVE.L D2,D1 
MOVE - 168(A62,D2 
EXT.L D2 
EXT.L D2 
SUB.L -106(A6),D2 
MULS.L -110(A6),D2 
ADD.L 01,02 


MOVEA.L 24(A6),A1 
ADDA.L D2,A1 

FMUL.X СА1),ЕРТ 
FADD.X -94CA6)2,FP7 
FMOVE.X FP7,-94CA6) 
ADDQ 35 1,- 170CA6) 
SUBQ.L 81,D5 

BGT lah_3 


Fortran, plain 

lae_3 MOVE - 164(А62,02 
EXT.L D2 
EXT.L D2 
SUB.L -134(A62,D2 
MULS.L 812,02 
MOVE.L D2,D0 
MOVE -162(A62,02 
EXT.L D2 
EXT.L 02 
SUB.L -122(462,D2 
MULS.L -126(A62,D2 
ADD.L D0,D2 
MOVEA.L 32(А6),А0 
ADDA.L 02,А0 


FMOVE.X (A0),FP7 ; get aCi,lO 


MOVE - 162 (462,02 
EXT.L D2 

EXT.L D2 

SUB.L -110СА62,02 
MULS.L 812,02 
MOVE.L D2,D1 

MOVE -160(A6),D2 
EXT.L D2 

EXT.L D2 

SUB.L -98CA6),D2 
MULS.L -102CA6),D2 
ADD.L D1,D2 
MOVEA.L 24(A6),A1 
ADDA.L D2,A1 


FMUL.X (A1),FP7 ; multiply by bCi,k) 


MOVE - 164(A6), D2 
EXT.L 02 

EXT.L D2 

SUB.L -158(A6),D2 
MULS.L #12,D2 
MOVE.L D2,D1 

MOVE - 16ØCA6) ,D2 
EXT.L D2 

EXT.L D2 

SUB.L -146(462,02 
MULS.L -150(462,02 
ADD.L D1,02 
MOVEA.L 40(462,A1 
ADDA.L D2,A1 


FADD.X (A D,FP7 ; add cCi,kO 


MOVE -164(A6),D2; this 
EXT.L D2; whole 

EXT.L D2; stuff 

SUB.L -158(A62,D2; is 
MULS.L *12,D2 ; 
MOVE.L D2,D1 ; R 

MOVE -160(A6),D2; E 
EXT.L D2; D 

EXT.L D2; U 

SUB.L -146(A6),D2; М 
MULS.L -150(462,02; D 
ADD.L D1,D2 ; A 
MOVEA.L 40(460),A41 ; N 
ADDA.L D2,A1 ; T !!!!] 


FMOVE.X FPT,CA1) ; put back cCi,k) 


ADDQ 1, - 162(A6) 
SUBQ.L #1,D5 
BGT 1ae.3 
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Debugging In MPW With SADE™ 
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in Computer Science from Eastern Michigan University, and is 
now a Master’ s of Computer Science degree candidate at Wayne 
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programming and software engineering. 


Introduction 
A good debugger is a programmer’s best friend. One of the 
serious drawbacks to MPW (Macintosh Programmer's Work- 
shop) software development has always been a lack of a source 
level debugger (no, I don't consider MacsBug hexadecimal 
dumps debugging!) Until now. Introducing SADE™ - the 
Symbolic Application Debugging Environment. This is Apple's 
new source level debugger for MPW 3.0 and beyond. 
In this article I plan to cover the following: 
° An overview of SADE. 
° SADE in action - debugging a sample C program. 
° A numerical integrator - pushing the SADE script 
language to the limit. 
° Talking straight - the good, the bad and the ugly. 
Note that even though this is nota ‘comparison’ article, I will 
occasionally mention THINK’s Lightspeed™ debuggers (be- 
cause of their excellent performance), as a frame of reference in 
discussing SADE. 


What Is SADE, Anyway? 

SADE is not an MPW tool, nor is it physically part of the 
MPW shell. It is simply a stand-alone application that commu- 
nicates with your target program under Multifinder. As in 
THINK’s Lightspeed C, this debugger must be operated under 
Multifinder, to allow interprocess communication. Two or more 
megs of memory are strongly recommended; however, the 
manual does indicate you can squeeze by with one meg. The only 
special requirements to run SADE are: 

1. You must be using Multifinder 6.1b7 or later. 
2. The (Pascal or C) compiler must be instructed to 
generate ‘symbol’ files during program compiles. 

One of the more interesting design decisions Apple made 
was to make SADE appear almost identical to the MPW Shell. 
This has both an advantage and a disadvantage: the advantage is 
that of instant familiarity to existing MPW programmers; the 
disadvantage is that this precludes the use of a user-friendly, 
animated interface (such as the debuggers used in THINK's 
Lightspeed C and Lightspeed Pascal). 

. Please refer to Figure 1 for a closer look at SADE’s 
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/HD100:MPW:SADE:SADE k 
“Source Ги. Asm] Debugging Worksheet 


Figure 1: The SADE Menu System 
functionality. 
Wade Through Your Code With SADE 
The most fundamental operation in using a debugger is 
setting a breakpoint in the source code. Because SADE is so 
sophisticated, there are four ways to do this: 


1. Enter the break command from the SADE command 
interpreter, The syntax (for debugging a C program) is: 


break «function name» .C«line number? ) 


2. Callthefunction SysError from within the C code itself. 
The syntax of this approach is: 


include <Errors.h> 


SysError(<integer from 129..3251D). 


3. Press the SADEKey (Command-Option-<period>). 


4. Openasource code file (as read-only from SADE), and 
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use the mouse to selectaline of code. Then execute ‘Break’ from 


the SourceCmds menu. 


Method number 1 is fine if your functions are small, other- 
wise counting the individual lines of code could prove cumber- 
some. 

Why does method number 2 work? When using version 
6.1b7 and above of Multifinder, MC68000 exceptions are passed 
to SADE, if present; if SADE isn’taconcurrently executing task, 
then a system exception occurs. 

Personally, I think method number 3 is somewhat satirical; 
trying to guess which machine instruction you are now (ahem, 
were) executing can cause brain damage. 

Method number 4, of course, appears to be the most user- 
friendly of them all. 

So in practice, it would seem that all methods except number 
three can be easily used to set break points in your own code. 
Refer to Figure 2 for an example of starting up SADE and setting 
breakpoints. For an illustration of SADE stopping at a break- 
point, please refer to Figure 3. The MPW C source listings will 
also provide more information on how to set breakpoints within 
your own code. 


© Sequence of SADE commands to begin the debugging session 
9 of the "Test" prograa. 


sourcepath ‘HD 100:Programmaing:Developaent Folder:MacTutor f: ' 


directory 'HD100:Programming:Developaent Folder:locTutor f:' 
targat 'Test' 


break main.C1) 
break func.C1) 


9 break at "number = 1" statement 
® stop once inside the func() procedure 


launch 'Test' 


n: 
БАЖ $000 000 ИЕ ШИТТІ 029) 


Figure 2: Launching the ‘Test’ program from SADE 


Address Break encountered at func.(1) 


Function Neme Line Number of Source 


Method One: Using the “Break” command to set e breakpoint 


Error number 129 at main.(4) 


Line Number of Source 


Method Two: Using e call to SysError() to set a breakpoint 


Function Neme 


Figure 3: Encountering source code breekpoints with SADE 
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One interesting thing I noticed is that a SysError() break- 
point will stop after that line of code is executed, whereas setting 
a normal breakpoint will stop before that line of code. 

SADE has complete facilities for keeping track of variable 
values. You can either perform a Show Value, which shows the 
contents of the variable of your choice, or you can use the Watch 
feature. This feature is analogous to THINK’s Lightspeed 
Pascal’s ‘Observe’ window: every time a variable’s value 
changes, it is updated in a display window for you. Please refer 
to Figure 4 for an example from the ‘Test’ program. 


SCS IK WOOO HD100:SRDE:Test Variables ZZ Bg) 


Step Two: When е “watch” variable chenges, SADE tells you about it. 


Figure 4: Observing variables change state 


And of course, you have complete code stepping facilities: 
single step lines of code, and even control whether or not you step 
into procedure calls. 


Program Your Bugs Away 

All of the aforementioned features can be found in most 
other debuggers. However, the feature that sets SADE apart from 
any other debugger I’ve used is its internal programming facility 
(henceforth, I’ ll refer to SADE programs as ‘scripts’, to differen- 
tiate these from your C & Pascal programs). You can actually 
write SADE procedures and functions to automate debugging 
tasks. And if that’s not enough, how about a slew of predefined 
procedures (even printf ) and reserved system variables? Fur- 
thermore, complete expression evaluation is possible, including 
pointer manipulation, bit-wise operations, and string manipula- 
tion. 

The script facility of SADE is so extensive, it strongly 
resembles Pascal. Not only that, SADE procedures and functions 
are fully capable of recursion. Unlike Pascal, however, all 
variables are dynamically typed - based on their use in the 
program; this would appear to be the result of an interpretative 
implementation of this language. 

To execute a SADE script, enter the script name (followed 
by any arguments) and press ‘enter’ from the numeric keypad. 
Thus, script invocation is identical to executing MPW tools. 
Before a SADE subroutine can be run, the file that contains it 
must first be loaded into memory; this is done as follows: 
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execute ‘<Full HFS Path»:«File Name?’ 


As an example, I’ve developed a general purpose numerical 
integration script, which when given any arbitrary function f(x), 
will find the (approximate) integral bounded between two values 
‘a’ and ‘b’. The foundation to my algorithm is the SADE eval 
function; this function takes a string representing an expression, 
and then proceeds to parse it in search of an answer. For example: 


define x = 5 
eval(‘x * 2”) 


When executed at the SADE command line, this would 
return “10” as the result. 

The technique of integration I use is called Simpson's Rule, 
which partitions an interval from ‘a’ to ‘b’ an even number of 
times (i.e. N=2M partitions). We then approximate the graph of 
к) by M segments of parabolas; the technique is shown below: 


b 
| f(x) dx = +[ f (x9) + 4f(x,) + 2f(x2) + 4f(xə) 
à + 2f(x4) + --- + f (xox) | Ax 


In my case, I partition each region between n and n+1 four 
times, giving delta x the value of 0.25; integration then simply 
becomes a matter of alternating the coefficients of the interme- 
diate data values. 

Unfortunately, it wasn’t that easy - because I wanted to be 
able to integrate any continuous function I could think of, not just 
the simple ones. As it turns out, simple mathematical functions 
_ (such as x**n) are not known to SADE, so I had to write my own. 

How did I do this for polynomials? Using something called 
a Taylor Expansion, it is possible to calculate x**n (x to the nth 
power), where either ‘x’ or ‘n’ can be floating point values. 
Taylor Expansions are open-ended functions, so itis necessary to 
determine a stopping criteria that is both accurate and efficient. 
The Taylor Expansion for x**n is shown below: 


x= | + піл) + nit)" (woo. - - 


For example: because both ‘x’ and ‘n’ can be floating point 
numbers, integrating the square root of ‘x’ is simply a matter of 
integrating x**(1/2) power. 

Just one more problem - In(x) is not known to SADE either, 
so here’s the approximation for it: 


z x-1 1 xy 1(®©2)*.. 
кб) = 2| t+ + = + s > 

This approximation, of course, is only valid for x > 0. For 
an example of a simple polynomial integration, please refer to 
Figure 5. 

However, before you throw away your favorite numerical 


analysis package, I should warn you that I found SADE to have 
problems maintaining floating point precision. Takealook at my 
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ҚОЗ ND100:...:Celculus Worksheet ЖЖж% 


execute ‘HD100:Programming:HacTutor f:Calculus Functions" 


Actual Invocation 

define f = 'x + exponent(x,0.5)' 
integrate (0, 1) 

1. 16518 


Meaning: 


1 
ER dx % 1.16518 
о 


Figure 5: Numerical Integration Using My SADE Script 


exponent script: I noticed that using tricks such as intermediate 
variables for subexpressions made the difference between a 
correct answer and something way out in left field. SADE’s 
natural habitat seems to be integers, which would make a lot of 
sense seeing how it’s a debugging environment. Therefore, even 
though Simpson’s Rule will (theoretically) work on any continu- 
ous function, my SADE script will only work in cases when 
SADE handles floating point calculations correctly. We should 
remember, that SADE is a debugging environment, so I don't 
consider this to be a drawback. 

If all these features still aren’t enough, SADE even provides 
high level calls to prompt the user with dialog boxes, add custom 
menus, and even generate music! In short, SADE has every 
power-tool a programmer could ever ask for in a debugger. 


Straight Talk About SADE 

SADE is by far the most sophisticated and user-extendable 
debugger I’ve ever used - but I do have one complaint: its user 
interface. This drawback is caused by SADE’s own complexity: 
at times it seems to offer you too many features. All of these 
features in turn dictate a user-interface that’s not as elegant as the 
Lightspeed debuggers. If SADE were made to be more user- 
friendly, even at the expense of some of its bells and whistles, 
Apple would have a world-class debugger in their hands. 


The End... 


MacsBug, MPW, Multifinder and SADE are trademarks of 
Apple Computer, Inc. Lightspeed is a registered trademark of 
Lightspeed, Inc. 

The opinions expressed here are solely those of the author, 
and not of Bell Northern Research Inc., or its employees. 
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A simple but powerful use of the SADE™ 
script langauge to perform numercial 
integration on almost any function. 


Copyright © Joe Pillera, 1989 
All Rights reserved 


пи} 3$ 3$ 3$ Á 3$ dH #@ 


func integrate(a,b) 


Integrate a global function ‘f(x)’ from 
a to b. 


INPUTS: 
a > integer or floating point 
b — integer or floating point 


— 13$ 13$ + + 32 3$ 3$ 3$ #9# SR 


unc integrateClower,upper) 
define factor, result, index, x 
index := lower 
factor := 2 
result := 0 
while index <= upper 
x := index 
if Cindex = lower) or Cindex = upper) then 
result := result + eval(f) 
else 
result := result + (factor * eval(f)) 
end 
index := index + 0.25 
if factor = 2 then 


factor := 4 
else 
factor := 2 
end 
end 
return С1.0/12.0) * result 
end 
I -...--------------------- 
# func In(x) -> Compute natural log of x 
Н зс x pe eee rene 
# INPUTS: 
# x -> integer or floating point 
jN; = Efe MS 
func In(x) 
define result, term, index, frac 
term := (x - 1.0) / (x + 1.0) 
result := term + (0.3333 * power(term,3)) 
index := 5 


while index <= 25 do 
frac := 1.0 / index 
result := result + 
(frac * power(term, index)) 
index := index + 2 
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end 
return (2.8 * result) 


end 

H-——————————————— 

# func exponent(a,x) -> Compute а ** x 
Hl I LE S 

# INPUTS: 

# a -> integer or floating point 

# x -> integer or floating point 

г. a 

# NOTE: Use power(a,x) if ‘x’ is a integer, 
8 because that routine is faster. 
в 


func exponent(a,x) 
define result,iteration,term 
define numerator , denominator 
term := x * ]n(a) 
result := 1.0 + term 
for iteration := 2 to 15 do 
numerator := power(term, iteration) 
denominator := factCiteration) 
result := result + 
Cnumerator / denominator) 
end 
return result 
end 


func power(x,n) -? Compute x ** n 
INPUTS: 

x — integer or floating point 

n — integer 


NOTE: Use iteration for speed. 


— + 1$ 1$ T T 3$ 3$ 3$ # 


unc power(x,n) 
define index, result 
if n = 0 then 
return 1 
elseif n = 1 then 
return x 
else 
result := x 
for index := 2 to n do 
result := result * x 
end 
return result 
end 


® func fact(n) -> Compute n! 
g; 22 —— > 
# INPUTS: 
# n -> integer 
t 
func fact(n) 
if n = 0 then 
return 1 
elseif n = 1 then 
return 1 
else 
return ( n * fact(n-1) ) 
end 


Sinclude “Errors.h> 
int number; 


Bainc) 
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/* Set breakpoint 81 here (from SADE) */ 
number = 1; 


/* Now pass control to func, and let */ 
/* it alter the “number” variable. */ 
Гипс ОО; 


/* Hard code breakpoint 83 here */ 
SusError(129); 


extern int number; 
void func() 


/* Set breakpoint 82 here (from SADE) */ 
number = 10; 


*include "SysTgpes.r^ 


resource ‘vers’ (1) ( 


); 


resource ‘vers’ (2) ( 
0х1, 
0x00, 
release, 


Test ff Test.meke test.r 

Rez test.r -append -o Test 
func.c.o f Test.make func.c 

C -sym on func.c 
main.c.o f Test.make main.c 

C -sym on main.c 


SOURCES 


= test.r func.c main.c 
OBJECTS = f 


unc.c.0 main.c.o 


Test ff Test.make (OBJECTS) 
Link -w -t APPL -c '????' -sym on -mf ò 
(OBJECTS) à 


0х1, * (CLibraries)"CRuntime.o д 

0x00, * (Libraries)"Interface.o д 

release, * (CLibreries)"StdCLib.o à 

0x0, * (CLibraries)"CSANELib.o à 

verUS, * (CLibraries)"Math.o д ES 
ua * (CLibraries)"CInterface.o д Sol 
“1.8 / MacTutor Magazine” -0 Test ГЕТ 
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Developer's Notes 
New Typographic Frontier 


Apple's New Typographic Universe 

At the 1989 Developers' Conference, Apple revealed an 
entirely new typographic universe to 1500 eager supporters. The 
combination of a new font technology, a greatly enhanced line 
layout manager, and an entirely new printer driver architecture 
promises to make the Macintosh the premier machine for print- 
oriented graphics, and open new opportunities for Macintosh 
developers. The three features are closely related and need to be 
discussed together to understand the full impact. 


Why Outline Fonts? 

The two great advantages of outline fonts are the ability to 
display them nicely at any point size, and their compactness when 
compared to a reasonably large set of bitmaps. For example, the 
full set of bitmaps for the (exceptionally nice) Clairvaux font 
occupies over 200K, while the outline description is estimated to 
average 40-60K. They are not magic, however - just a shorthand 
method for describing bitmaps. 

Ultimately, all raster devices actually use bitmaps to place 
the characters of a font into an image; it doesn’t matter whether 
you re talking about a 2540 dpi Linotronic imagesetter or a 72 dpi 
128K Macintosh. What outline fonts provide is an efficient way 
to generate a bitmap of a specified character at an arbitrary size 
that can then be saved and used whenever needed. The “quality” 
of an outline font system depends on two factors: 

1) The quality of the generated bitmap. If the bitmap gener- 
ated by the process is not visually appealing, nothing else 
matters. 

2) The speed of the generation process. If it takes forever to 
create a bitmap of a character, who would use that process? 

The process of generating a bitmap consists, for both the 
Apple and Postscript systems, of two basic parts: creating the 
basic bitmap, and making any small adjustments necessary for 
the best appearance at small point sizes. Creating the bitmap from 
an outline description can be visualized as drawing the outline 
over a grid of small squares, and filling in all the squares that fall 
at least partially within the outline. 

If you carried out this little exercise, you were probably 
bothered by some of the effects of filling in squares that only 
partially fell within the outline. This demonstrates the problems 
encountered with small type on machines with relatively low 
resolution (large pixels). Small point sizes are a problem for all 
systems simply because: 

1) With low resolution and small point sizes, a single pixel 
occupies a significant percentage of an image. Therefore, it is 
important to make sure every pixel is optimally placed. 

2) “The jaggies” are unavoidable, but a visual decision on 
where a pixel looks best sometimes differs from a purely mathe- 
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matical decision. Naturally, this conflict is more significant when 
there are only a few pixels to play with. 

3) While the idealized pixel is generally square, real world 
pixels never are, whether you are dealing with a CRT or a 
LaserWriter imaging drum. This means that corrections must be 
made to account for the visual effects of the actual pixel shapes 
on the equipment being used. There are two basic shapes of “real” 
pixels: 


“Write 
White” Pixel 


"Write 
Black” Pixel 


Real World Pixels — 


The reason for the different shapes is that in reality all pixels 
tend to be convex; however, when convex white pixels are drawn 
over black to define a black pixel, the black pixel is left with 
concave edges. 

One of the major advantages of the Apple outline font 
system from the artist’s viewpoint is that the entire “hinting” 
language needed to make the bitmap adjustments is precisely 
defined in complete detail; this is in contrast to the undocumented 
system used by Adobe, which has historically given them a small 
but important advantage over their competitors in image quality. 
The features included in the hinting language were chosen to 
include all the features used by the major type foundries, thus 
making the conversion of fonts by those type foundries to the 
Apple format as accurate as possible. The result should be a 
steady flow of very high quality fonts once System 7.0 is in place. 
In fact, Apple has been working with most of the major type 
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foundries in developing their system. 


Another result of Apple’s decision to publish the complete. 


specifications of its outline font system is that we can expect to 
see one or more font editors enter the market that will allow the 
artist to completely specify the hinting required for the best 
possible quality at small point sizes. This levels the playing field 
and places the competitive emphasis on artistic ability rather than 
secret technology, which will be to everyone’s benefit in the long 
run. 

Apple’s font descriptions, using quadratic splines, are de- 
signed to be simple enough that it is reasonable to use them for 
interactive displays such as the Macintosh itself; the original 
Postscript model (which uses Bezier curves - a more complex 
equation form) is oriented towards printing engines. The funda- 
mental approach is to generate the required bitmaps for an entire 
size when first requested and cache them; thus, the overhead is 
only incurred once. Once the bitmaps have been built, the 
Macintosh text operations are exactly as fast as when using the 
“old” fonts. “Old style” fonts are completely compatible with 
the new system. This means that you won't need to throw out all 
those nifty display fonts you already have when you install 
System 7.0 


What's so Important about the new Line Layout 
Manager? 

While the new font manager provides very precise control of 
the shape of letters, the new line layout manager provides some 
very powerful and impressive capabilities in conjunction with 
the new font descriptions. One of the primary goals of this 
manager is to work together with the Text Edit package, using 
information provided in the font descriptions, to greatly enhance 
the line layout facilities available to the developer and user. The 
preliminary description handed out at the Developers' Confer- 
ence noted that many of the features of the Layout Manager, 
while optional in English and other roman-script languages, are 
mandatory for acceptable text display in many other languages. 

There are two basic types of features implemented in the 
Layout Manager: Positional features, and Non-positional fea- 
tures. As you probably have deduced from the names, the 
positional features affect horizontal and vertical positioning of 
characters, while non-positional features primarily affect charac- 
ter shaping. The distinction will become clearer when I list some 
of the individual items in each group. 

Positional Features. These include the types of manipula- 
tions traditionally considered part of “fine typography", such as 

e Kerning: This is the most basic positional manipulation. It 
involves moving a pair of characters (such as T-y) closer together 
to improve the appearance of the text. When “negative kerning" 
is done it is often termed letterspacing. 

* Optical alignment: This is the adjustment of positioning so 
that margins are optically correct. The problem arises because of 
the space surrounding a character that is part of it's definition. 

e Hanging punctuation: Punctuation marks are often placed 
"outside" the margins since they are optically small so that the 
optical flushness of the margins looks better. A line ending with 
a period, for example, seems to be visually slightly ragged. 
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* Justification and centering: Just what they sound like. 


Non-positional features. These are features that concentrate 
on refining the shape of letters, primarily in response to the 
immediate context for each letter. Many of these features were 
difficult to implement, to say the least, with a traditional typeset- 
ting system. A partial list of these features includes: 

* Ligaturing: This is the combination of two letters into a 
single graphic, and was traditionally done both for more compact 
layout and for a more elegant appearance. Common ligatures 
include “æ”, “се”, etc. 

* Contextual forms: As the name suggests, this is a technique 
for shaping a letter to look best in a very specific context. For 
example, a capital ‘L’ with a long low horizontal stroke that goes 
under the succeeding character is very attractive as long as the 
succeeding character doesn't have a descender. With contextual 
reforming, the Layout Manager can chose a non-underlining 
form if the succeeding character has a descender. For example: 


* Applied marks: These are typically various forms of 
accents, such as the tilde (~) or accent (°). There are various styles 
of positioning these. 

* Reordering of graphics: In certain non-roman languages, 
such as Sanskrit, the order of characters is dominated by their 
shape, so that the visible order of certain character combinations 
may not correspond to their logical order. This reordering, 
fortunately, follows firm rules and not artistic whim. 


It should be emphasized that the modifications that can be 
applied by the Layout Manager happen fast enough to be very 
real-time. Many of the features of the Layout Manager are 
specified in the font description, so that the type artist can have 
precise control over contextual reformatting, for example, which 
is automatically applied without any intervention by the applica- 
tion. 

Certain Text Edit functions are now better carried out by the 


Layout Manager. In particular, these include the text measuring 


and caret management functions, which are very dependent on 
the higher precision supported. Highlighting can now be non- 
rectangular and non-contiguous, for example. As in FullWrite, a 
caret in italic text is slanted at the proper angle, which actually 
serves to make placement much easier. 

The combination of the new font descriptions and the power 
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of the Layout Manager gives the Mac user the power to create text 
with every typographic refinement available to the traditional 
typesetter, and then some. Up until now, however, everything 
I’ve talked about seems to have been limited to the screen - so 
what good does it do when the ink hits the paper? 


The New Printing Architecture - Getting It All 
Down in Black and White. 

And other colors as well, of course... Printer drivers have 
always been one of the sore spots in the Macintosh architecture, 
being extremely difficult to write well and tending towards 
instability. Apple’s stated goals for System 7.0 required that the 
entire internal design approach for these drivers be changed. As 
a result, the new drivers are totally new code, with considerable 
advantages. 

The new driver structure is explicitly layered into: (1) An I/ 
O layer specialized for a number of device types, (2) A "Food 
Processor" layer that handles the bulk of the work of dicing, 
slicing, and chopping the user's requests into device-specific 
byte streams, and (3) A specification layer, making up about 10% 
of a driver, that is actually written by the driver author to describe 
the hardware-dependent aspects of the device and thus convert 
generic requests by the user into specific calls to the food 
processor, where the actual conversions take place. 
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Input/Output Controllers 


Plotter 


Dot-Matrix Ж 


PostScript 


As shown in the diagram, there are several different devices 
supported. According to an experienced printer-driver author I 
spoke to, driving a film recorder is actually the most difficult, due 
to extremely stringent timing constraints. Perhaps the most 
interesting from a marketing viewpoint is the “R.I.P.” - the Raster 
Image Processor that forms the heart of the modern typesetter, or 
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imagesetter. While it was firmly stated that Apple would never 
license the technology at the core of the image creation process, 
a Mac II-class machine with an EtherNet card would be very 
viable as the heart of a relatively low-price high resolution 
typesetter that could very effectively compete with a Postscript 
typesetter. I don't expect that it will take too long for such a 
device to appear on the market... 

Unlike the previous structure, the new printer manager is 
explicitly designed to simplify the task of writing output drivers 
as much as possible. The authors claimed at the Developers' 
Conference that the average time to create a printer driver would 
decrease from months to days, and that they had created several 
test drivers in less than a day. 

The motivation for the support of 3rd party devices is simple: 
Apple has decided that support for the widest possible variety of 
printers, plotters, etc. is necessary to make the Mac the printing 
platform of choice. As conclusive evidence of this, they revealed 
that the "print shop" is now committed to actively supporting 
everyone who wishes to make a Mac-compatible printer - even 
as a result. 

There are a number of additional major enhancements to the 
printing capabilities of the Mac. Among the more important ones 
are: 

• The ability to redirect spooled output after before printing. 
This means that if a particular LaserWriter turns out to be 
extremely busy, you can send a waiting document to another 
printer without having to reprint it. For this alone, most people 
would be ecstatic. 

° The ability to redirect a printed document to a printer of a 
different type without having to reprint it, and without having the 
layout recalculated. This may require some cooperation on the 
partof theapplication authors; the basic ideais the the application 
will output both a "final" quality and a “draft” quality version at 
the same time; the draft quality component will use the layout 
information for the final quality portion. This means that you can 
choose a LaserWriter for the final output device, but send the 
document to an ImageWriter II and get an accurate idea of the 
final appearance. 

* The ability to keep a spooled document after it's been 
printed, so that munged pages could be reprinted if necessary. 

* Further off in the future (post-System 7.0), support for 
high-volume remote printing stations that would include mul- 
tiple output queues (so you could just say “Use the 1st available 
LaserWriter" rather than having to explicitly pick one), good 
status reporting, and other features designed to work in an 
environment such as many large offices. 

° Greatly redesigned user-interfaces for the printer dialogs, 
allowing you to choose a printer from a printer dialog, set a 
custom page size for a job, and support multiple page types in a 
single job (such as a #10 envelope and legal paper), among other 
things. 


From the viewpoint of an application developer, there were 
several critical matters that are being handled properly in the new 
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approach. First, the application’s interface to the printer drivers 
is structurally identical to the way matters work today, although 
routine names have been changed to protect the innocent. This 
means - hopefully - that a simple conversion will be all that’s 
needed to become printing compatible with System 7.0. Sec- 
ondly, recognizing that the new functionality is too radically 
different from that in pre-System 7.0 systems, Apple is making 
no attempt to make the new drivers work in older systems - which 
means that past mistakes are not going to be anchors on the new 
drivers. The downside is that no existing drivers will work under 
System 7.0, but changing printer drivers is a fairly trivial matter. 
Finally, the print shop claimed the new drivers are noticeably 
faster than the older drivers - which cheered everybody. 

Perhaps the most important fact was that the print samples 
shown were of uniformly excellent quality. I once worked for a 
typesetter manufacturer, and the output I saw at the Developers’ 
Conference was on a par with “real” typesetters. 


What’s ahead in the future? 

As if all these developments weren’t enough, a little infor- 
mation about future developments leaked out - just enough to 
tantalize. The Remote Printing Stations were fairly explicitly 
described, but we were cautioned that they wouldn't be ready in 
time for System 7.0. It was stated that the new font system will 
support rotated text, but that the current implementation of 
Quickdraw couldn’ handle it. And finally, somebody in develop- 
ment was overhead mentioning that the resolution-independent 


version of Quickdraw would support the rotated text, but that an 


implementation compatible with existing applications was prov- 
ing difficult and was “a ways off”. 

So much for my Robert Cringely imitation; now back to 
reality... 


What do these developments actually mean? 

The most important outcome from these new developments 
is that finally a single imaging model will be usable on everything 
from the Mac screen to a high-resolution imagesetter, eliminat- 
ing the mis-matches that now make WYSIWYG really mean 
"What You See Is Almost What You Get". This gives Apple a 
dramatic advantage over competing machines, where there are 
always differences between the screen and hardcopy graphic 
models, with the ensuing annoyances. 

From the users' viewpoint, the most noticeable immediate 
change will be that the quality of text on the screen is going to 
improve dramatically, This should make the Mac even more 
competitive against the MS-DOS machines. Once the user starts 
printing documents, the new speed and flexibility should be very 
pleasing. 

It should be emphasized that your Postscript fonts and 
printers don't become instantly obsolete with System 7.0. The 
Postscript drivers are intelligent enough to determine if you are 
using aresident font and to use that directly, rather than try to stuff 
the Apple version of Courier into a PostScript printer. 

Ultimately, we all win - better output and applications for the 
user, and a larger market for the developer! < 


«Қы» 
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Overriding ROM Resources 
Ronny Zulaikha 
Sydney, Australia 

When Apple upgraded to the 128K ROM, some of the extra 
space was filled with ROM resources that were previously only 
held in the system file. This saves time in that these resources 
aren't loaded from the system file when needed, and saves space 
in that RAM isn't taken up by them. 

If one is designing a resource that is to replace one in the 
ROM, merely placing the new resource in the system file is not 
sufficient. As described in IM IV-20, one needs an ‘ROvr’ 
resource ID 0, which my system file (4.3) already had. This 
resource startup scans the system file for *ROv#' resources of any 
ID, which indicates what resources to override. The first word of 
a ‘ROv#’ resource is the version number of ROM to override, and 
is $75 for the 128K ROM. For the SE and Mac II, it would be 
reasonable to assume that the version numbers listed in IM V-xvii 
would apply, $76 and $78 respectively. In fact, the routine in the 
“КОуг” resource checks against the version word at location 8 
higher than the start of the ROM. The high order byte is 0 for the 
128K ROM, 1 for the Mac II and 2 for the SE, while the low order 
byte is the ROM version number. Putting this together, we get 
$276 for SE and $178 for the Mac II 

Optimized String Comparisons 
John S. Stokes lil 
San Diego, CA 

My routine to compare two Pascal strings uses substantially 
less code than the "optimized" routine published in Donald 
Koscheka's HyperChat column in November, 1988 issue of 
MacTutor. In my routine, the Pascal string length fields are 
compared as just another character in the comparison loop 
instead of separately. 


Ad - Pascal string 1 
Al - Pascal string 2 
00 <- Q if false, 1 if true 
01 < work 
CompareString Moveq %0,00 ; initialize flase return 
code 
Move.B (A0),D1 ; length of the first string 
Ext.W Di ; dbra uses word 
610 Cmp.B (A0)+,(A1)+; match? 
Bne.S 60900 ; no 
Dbra 01,610 ; yes, continue 
Moveq #1,D0 ; Set return code to true 
0900 Rts ; return 
Power Supply Board 


David B. Lamkins 
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Thanks to MacTutor, my Mac is alive and well at minimal 
expense following a sudden failure of the power supply board. 
Over a period of a couple weeks, under light use, my screen went 
from an occasional “blink” (accompanied by a snapping sound) 
to a thin vertical line. I recalled that there was a discussion of 
these symptoms in Mactutor, and found a detailed description of 
the problem and its cure in the June and July 1987 issues. 

I'd like to shed some additional light on the subject, since I 
suspect that many owners of older Macs will face the same 
problem eventually. The Macintosh power supply board (which 
also provides the circuitry to operate the display) contains a wide 
range of parts, from integrated circuits to high-power compo- 
nents. Itis tricky to solder the full range of these components on 
a wave solder machine —too little heat and the leads of the large 
components don't get properly soldered, too much heat and the 
delicate components get fried. 

Ifounda crack around J1 pin4, justas indicated in the earlier 
articles, and signs of developing cracks around the other pins of 
Jl. I removed the old solder with a solder bulb and carefully 
resoldered all four pins. What surprised me was that I found that 
NO solder had flowed between the pins and the(I'm assuming — 
too late to check) plated through holes in the PC board. Thus, the 
contact area was limited to a very thin film of solder bridging the 
connector pin to the foil on the PC board. It's no wonder there 
was local heating leading to a joint failure! 

I also found a bad solder joint on one of the leads of a coil in 
the same horizontal sweep circuit, and resoldered that as well. In 
this case, it looked like the original connection suffered from 
either impropercleaning of the coil lead, or too little flux and heat 
during soldering. A quick check of the solder joints on the 
remaining showed a potential problem on the end pins of the ten- 
pin power connector. Note that none of these problems were 
plainly visible to the naked eye —a magnifying glass was 
required 

I found that the hardest part of the repair was locating the 
appropriate tools to open the Mac's case. The readily available 
MacSnap Toolkit is not worth the expense —a long piece of allen 
wrench stock, which fits only some of the screws, is supplied in 
lieu of a Torx screwdriver. I returned this immediately for a 
refund. Local hardware, auto supply, appliance service, and 
specialty tool stores (I tried at least fifteen altogether) failed to 
produce a long-shafted Torx T-15 screwdriver. Least helpful 
was the service department of the local Apple dealer —"Sorry, 
they're made exclusively for Apple. You can't buy one unless 
you're an authorized Apple repair center." Finally, I turned to the 
MacTutor advertisers and called Computer Quick. For $20, 
these folks sold me a toolkit (separate screwdriver and case 
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spreader) as good as any seen in an Apple service department. 

My Mac started life three and a half years ago asa 512K. A 
year later, it was upgraded to a 512 enhanced, and stuffed with 4 
megsof RAMandapiezo fana year after the first upgrade. Ihave 
never had even a hint of a power supply problem during all this 
time. The time from onset of the first “glitch” to total failure was 
only a couple of weeks of light use —perhaps twenty hours of 
power-on time. From what I’ve seen, I strongly recommend that 
owners of earlier Macs take very seriously any signs of trouble 
with their display. 

Whatever you do, don’t “fix” a jittery display by banging on 
the side of the case, as I’ve heard some people will do —this will 
only prolong the symptoms and probably will cause more exten- 
sive damage due to internal heating of bad solder joints. If you 
see the onset of this problem, you probably shouldn’t leave your 
Mac unattended while powered on. I suspect that the failure of 
the yoke connection for the horizontal sweep could unduly stress 
related components, leading to more serious failures than can be 
recovered with touch-up soldering. 

Finally, if you do experience the “thin vertical line” death of 
your Macintosh, check the solder joints as mentioned here. If you 
don’t know how to solder, or have never worked on a television 
or video monitor circuit, enlist the help and advice of a friend who 
has. Failing that, you may want to consider a board exchange via 
some outfit like Computer Quick on the west coast, or Pre- 
owned Electronics in the Boston area. You'll save money and 
time compared to the service provided by many Apple dealers. 

Linear Equations 
C. H. Friend 
Watford, Herts, England 

The article by Dave Kelly in the September MacTutor takes 
a long way around to do the following, which is the way it would 
appear in most math textbooks about solving linear systems of 
equations: 

REM Solve equation system using inversion by MAT routines 
REM mod CHF: 2/10/88 for TrueBasic 2.0 on Mac II 
OPTION BASE 1 

DIM AC3,3), V(3,3), BC3, D, XC3, 1) 

REM MacTutor Sep’88 example: 

REM coefficient matrix [A]: 

DATA 1, -4, 4, -1, 6, -3, 1, Ø, -1 ! equation coefficients 
REM right-hand side vector (b): 

DATA 7, 0, 7 ! equation data 

REM System is [A]x(X) = Cb) 

MAT READ A 

MAT READ B 

PRINT “Coefficients: ” 

MAT PRINT A 

REM inverse of coeff. matrix, [A]“-1 

MAT V=INVCA) 

PRINT “Inverse: ” 

MAT PRINT V 

PRINT “right-hand sides:” 

MAT PRINT B 

REM Solution vector, (X) = [A]*-1 x (b) 

MAT X= V * B 

PRINT “Solution: ” 

MAT PRINT X 


END 


Results obtained are shown below: 
Ok. run 
Coefficients: 
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1 -4 4 

=] 6 -3 

1 0 -1 

Inverse: 

‚428511 ‚285714 ‚857143 
‚285114 .357 143 7. 14286е-2 
.428571 .2857 14 -, 142857 
right-hand sides: 

7 

0 

1 

Solution 

9 

2.5 

2 

Ok. Bye 


You also refer to Hewlett-Packard Basic, on HP9000 Series 
machines. The Matrix ROM on HP’s smaller Series 80 machines 
has had an extensive set of matrix commands and functions for 
some time. Series 200 HP-Basic has only just acquired some of 
these, such as the sub-matrix copy commands. Other useful HP- 
Basic functions are the row and column sums. These make 
powerful programs very short, e.g. the following example from 
“Probability and Statistics for Engineers and Scientists” by 
Walpole and Myers (MacMillan) 


REM Multiple Linear Regression (W&M), HP86 

REM mod 25/6/88 for TrueBasic on Mac II 

OPTION BASE 1 

DIM DC5, 15), Е(15,5), FC1,5), VC15,4), Х(15,5), TCS, 15) 
DIM А(5,5), С(5,5), YC15, D, 201,15), 6C1, 15), HC5, D 
DIM BC5, 1), РС5, 1), Y2C15) 

DATA 4, 13 

DATA 25.5, 31.2, 25.9, 38.4, 18.4, 26.7, 26.4, 
DATA 25.9, 32, 25.2, 39.7, 35.7, 26.5 

DATA 1.74, 6.32, 6.22, 10.52, 1.19, 1.22, 4.1 

DATA 6.32, 4.08, 4.15, 10.15, 1.72, 1.7 

DATA 5.3, 5.42, 8.41, 4.63, 11.6, 5.85, 6.62, 8.72 
DATA 4.42, 7.6, 4.83, 3.12, 5.3 

DATA 10.8, 9.4, 7.2, 8.5, 9.4, 9.9, 8, 9.1 

DATA 8.7, 9.2, 9.4, 7.6, 8.2 

REM 

PRINT “Multiple Linear Regression: ” 

READ K,N 

MAT REDIM DCK,ND, ECN,K), FC1,K) VCN,K- D 

MAT REDIM ХСМ,К), TCK,N) ACK,K), YCN, 1) 

MAT REDIM ZC1,ND, GC1,K), НСК, 1), РСК, 1) 

MAT READ D 

REM 

МАТ E = TrnCD) 

PRINT “Data:” 

MAT PRINT USING "sunun un^: E 

REM MAT F=CSUM (E) ! HP-BASIC 

FOR J = 1 ТО К ! TRUEBASIC 


FOR I = 1 TON 
LET FC1,J) = РС1,Ј) + ECI,J) 
NEXT I 
NEXT J 


PRINT “Sums: ” 

MAT PRINT USING “96888 u^. F 

MAT X=Con 

КЕМ MAT V=EC,2:K) ! HP-BASIC 

FOR I = 1 TON ! TRUE BASIC 
FOR J = 1 TO K-1 
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LET V(I,J) = E(I,J+1) 
NEXT J 
NEXT I 
REM МАТ XC(,2:K)=V ! HP-BASIC 
FOR I = 1 TON ! TRUE BASIC 
FOR J= 1 TO K-i 
LET X(I,J+1) = VCI,J) 
NEXT J 
NEXT I 
REM PRINT “Ind. variables: ” 
MAT T = TrnOO 
МАТА = ТЕХ 
PRINT “Equations: ” 
MAT PRINT USING “бинин шш”. A 
REM MAT Y=EC, 1) 
FOR I= 1 TON 
LET Y(1,1) s ECI, D 
NEXT I 
МАТ Z = TrnCY) 
MATG=Z * X 
MAT PRINT USING "naung nun». G 
МАТ H = TrnC6) 


REM MAT B=SYS (A,H) ! HP-BASIC, solves linear system 


МАТ C = InvCAD ! TRUE BASIC 
MATB=C* H 

PRINT “Coefficients: * 

MAT PRINT USING “—, sanang» .g ~ 
PRINT “residuals: ” 


REM МАТ Ү2=Ү.Ү | HP-BASIC allows dot product of vectors 


FOR I = 1 TON 
LET Y2CI) = YCI, 1) 
NEXT I 


REM SY2=SUM (Y2) | HP-BASIC matrix function 


LET SY2 = 0.0 
FOR I = 1 TON 

(ЕТ SY2 = SY2 + Y2(I) 
NEXT I 
LET SY2N = GC1, 12*2/N 
LET SST = SY2 - SY2N 
MAT P = Trn(G) 
REM MAT P=B.P 
FOR J = 170 K 

LET PCJ, 1) = BCU, D*PCJ, D 
NEXT J 


LET 586- = 0.0 
FOR J = 170 K 
(ЕТ 586 = SBG + PCJ, D 
NEXT J 
LET SSA = SBG - SY2N 
LET NOF = N - K 


LET ES2 = (SST - SSA)/NDF 
PRINT USING “SST = Saat sau”: SST, 


PRINT USING “, SSR = nenn mun». SSR; 


PRINT USING *; s^2 = #88, пинин», ES2 
END 

Results are: 

Ok. run 


Multiple Linear Regression: 
Data: 


25.50 1.74 5.30 
31.28 6.32 5.42 
25.90 6.22 8.41 
38.40 10.52 4.63 
18.40 1.19 11.60 
26.10 1.22 5.85 
26.40 4.10 6.62 
25.90 6.32 8.72 
32.00 4.08 4.42 
25.20 4.15 1.60 
39.70 10.15 4.83 
35.70 1.12 3.12 
26.50 1.70 9.30 
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10.00 
9.40 
1.20 
8.50 
9.40 
9.90 
8.00 
9.10 
8.10 
9.20 
9.40 
1.60 
8.20 


Sums: 
371.50 59.43 81.82 115.40 


Equations: 
13.000 59.430 81.820 115.400 
59.430 394.726 360.662 522.078 
81.820 360 . 662 576.726 128.310 
115.400 522.078 128.310 1035 .960 


377.500 1877.567 2246.661 3337.780 


Coefficients: 
39. 157350 
1.016100 
-1.861649 
-.9343260 


residuals: 
SST = 438.131, SSR = 399.454; s'2 = 4.29738 


Ok. Bye 

Matrix statements were in the original DEC PDP Basic, 
developed by Kemeny and Kurtz. They were omitted from early 
microcomputer Basics, presumably for memory reasons. An- 
other less useful feature of DEC Basic is this “ННН” print image 
stuff, HP-Basic uses the much neater “nD.mD” style (numbers of 
digits before and after the decimal point, plus other options for 
mantissa and exponent style, etc. [Thank you for an excellent 
treatment of an interesting subject. I am very interested in 
covering more such areas in scientific and engineering comput- 
ing. After all, computers were origonally designed to solve 
problems, were they not? —Ed] 
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Update to Event Simulator 
Matthew Snyder 
Fairfield, CA 

Another weekend, another thought about Event Simulator. 
This thought is a minor one, though, and I’m not even sure if it’s 
significant enough to merit a change. [This letter refers to a 
program published in the January 1989 issue of MacTutor. -Ed] 

The change would be a minor one, too. Right before the 
heading How the Demo Works and right after that long paragraph 
about memory, I would add this paragraph: 

"I could have avoided the memory problem by using PPos- 
tEvent instead of Enqueue. PPostEvent takes an event type and 
message as arguments, and creates an event using current mouse 
position, modifier keys, etc., posts the event, and returns to you 
a pointer to the new queue element. Youcan then use that pointer 
to modify the event to your liking. However, I found this method 
unsatisfactory for a general library because the size of the Event 
Queue Buffer limits you to 20 consecutive events." 

I was trying to imagine what type of critical letters I could 
expect from readers, and it occurred to me that anyone that’s done 
this kind of thing before has probably used PPostEvent. “Why 
didn’t you use PPostEvent? Don’t you have acopy of Inside Mac 
IV? It’s easy. Here’s how...” The disclaimer above explains 
why I didn’t use PPostEvent. 

[Thank you, Matthew, for your update. Matthew isone of the 
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more concientuous writers, always thinking about his article, 
even after it has been submitted. Unfortunately, this letter came 
to me just as [was proofing the final proofs of the journal. -KC] 
MacFortran/020 Math Library 
Tatsuhito Koya 
Evanston, IL 

Being a student, I have been on a tight budget lately. I had 
to terminate most of my magazine subscriptions, but I have 
decided to keep MacUser, Computer Shopper, and MacTutor. 
These three magazines have been the main sources of informa- 
tion about what is happening in the world of personal comput- 
ing—the world of the Macintosh, specifically. 

I am not a computer science major; hence, it is difficult for 
me to find time to develop my programming skill, yet I do have 
opportunities to use computers for engineering computations. I 
do most of my computations on the main frame, but I would really 
like to use my Mac as well. I have MacFortran/020, but the 
problem is that I cannot find a math library for it anywhere. 
Moreover, Edit text editor is not one of the best program editors 
around. I would really appreciate it if you could recommend me 
a good math library (modifiable preferred) and a program editor. 

[I called Absoft to check on the math library; unfortunately, 
they knew of none, but they seemed to like the idea; maybe our 
readers know of a library out there, or will create one. -KC] 

[As for a text editor, I would suggest a new Fortran specific 
editor called FREDITOR 1.0 from Battelle Pacific Northwest 
Laboratories, PO Box 999, Richland, WA 99352. Our good 
friend Bill Rausch wrote the manual. The editor was written in 
Lishgtspeed C and used the LS CAPPS Editor construction kit. 
-Ed] 

IAC Driver 
Lawrence D'Oliveiro 
Hamilton, New Zealand 

I read the articles on the IAC driver by Frank Alviani 
and Paul Snively with great interest. The Mac certainly needs a 
capability like this. However, a couple of questions. 

First of all, why does the driver need to save multiple 
editions of a source extent? It only returns the latest one on any 
ReadData call anyway. 

Secondly, it would be useful to allow desk accessories to 
take advantage of IAC. And of course, you don't need MultiFin- 
der to run desk accessories. The check for the presence of 
MultiFinder is neat, but is it really necessay? 

As always, keep up the good work, and let's have even more 
thought provoking articles in MacTutor! [We'll do our best. -ed] 

[This letter gave me the excuse to call and talk to Frank 
Alviani. Frank, if you ever get the chance, is one of the nicest 
people to talk to, and I enjoyed the opportunity to call and see how 
things were going on his new house (not done as of this writing). 

Frank explained to me that although the main purpose of the 
driver is to give the most recent extent to the clients, there are a 
couple reasons to keep the old extents. The first is to give the 
client the ability to call older extents. This could be used for 
perhaps a “hot” undo feature. 

The second reason is useful for database type applications 
where each extent may want to be saved for future use. Lengthy 
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file operations may bring the client back in time to find himself 
several extent versions behind the current version. 

Your second question was a good one, also. Desk accesso- 
ries have the ability of file I/O. Also the driver itself makes 
ordinary calls. Therefore it is conceivable that the driver could 
be modified to work with desk accessories. The call to initialize 
the driver could say basically, "I don't care if MultiFinder is 
around." - KC] 

Animated Watch Cursor Typo 
Andy O'Brien 

Keep up the great work on a fine magazine. Even the letters 
contain little tidbits of information. I especially enjoyed David 
Stoops' letter in the December '88 issue. After keying it in (and 
getting the proper LSP error message). I Realized that the 
InitWatch procedure in the WatchUtilities unit had a typo in it. 
GetCursor was being called as a procedure when we all know it 
is a function. Here is what the procedure should look like. Take 
care and continued success 


porcedure InitWatch; 
var 
watchcount : 
begin 
WatchList := ecurHandle(GetResourceC'acur'/, 8)); 
with WatchList** do 
begin 
for watchcount := 1 to 8 do 
Watch(watchcount] := 
GetCursor(HiWord( longintCWatch[watchcount 122); 
whichWatch := 0; 
end; 
end; 


integer; 
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Watch Cursor Revisited 
Jan Eugenides 
Waterbury Center, VT 

David Stoops’ Animated Cursors from the December issue 
was interesting, but it had two deficiencies: 

1) It was hard-coded for eight cursors, instead of obtaining 
the real number of cursors from the ‘acur’ resource, 

2) Itused SetUpAS and RestoreAS, which should no longer 
be used. 

I recoded the example in MPW C 3.0b1, with the modifica- 
tions, and here is the result. I also changed to an 'acur' resource 
with an ID of 128, so as not to conflict with any system resources. 
The Rez source code for the watch ‘acur’ and the associated 


cursors are as follows: 
8include «Types.h» 
8include «Resources.h? 
"include «QuickDraw.h? 
Sinclude ‹0504115.һ 
*include «Retrace.h? 
"include «Memory.h? 
include «ToolUtils.h» 
"include <Strings.h> 

f include <Errors.h> 


typedef struct ( 
short numCurs; /*number of cursor “frames” */ 
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short whichCur ; 

CursHandle Сигѕ(1]; 
cursors here*/ 

)acur; 


typedef acur *acurPtr,**acurHandle; 


static acurHandle  CurList; 
static VBLTask VBL; 


/*used as “frame” counter*/ 
/*can actually be any number of 


pascal void AnimateWatch() /*the VBL routine*/ 


( 
long oldA5; 
oldA5 = SetCurrentA5(); 


ifCC*CurList)->»whichCur >= C*CurList)-»numCurs-1 ) 


C¥CurList)->whichCur = 0; 
else 
(*CurList)->whichCur ++; 


SetCursor(*((*CurList)->Curs({(*CurL ist )-»whichCur 122; 


VBL.vblCount = 10; 
РОХ 


InitWatch() 
( 


short curCount; 


CurList = CacurHandle)GetResource( ‘acur’, 128); 
forCcurCount = Ø; curCount < (*CurList)-»numCurs; curCount++) 


€*CurList)->Curs(curCount] = 


GetCursorCHiWordCClong)C*CurL ist )-»Curs[curCount])); 


C*CurList)->whichCur = 0; 
) 

Star tWatch() 

( 

OSErr err; 


VBL .qType = vType; 


VBL.vblAddr = CVBLProcPtr )AnimateWatch; 


VBL.vb1Count = 10; 
VBL . vblPhase = 0; 


err = VInstall((QElemPtr)&VBL); 
) 


бады 


OSErr err; 


т = VRemove((QElemP tr ЖҮВЇ.); 


®include "types.r"^ 


data ‘acur’ (128, locked, preload) { 


%%00 08 00 00 01 00 
%%01 03 00 00 01 04 
%%01 07 00 00" 


М 
resource ‘CURS’ (263, 
$^sF 00 ЗЕ 00 ЗЕ 00 
$"9C 60 80 40 80 40 
$"3F 00 ЗЕ 00 ЗЕ 00 
$^FF CO FF С0 FF CO 
(8, 8) 


J 

resource ‘CURS’ (262, 
$^3F 00 ЗЕ 00 ЗЕ 00 
$*BC 60 80 40 80 40 

 $"^sF 00 ЗЕ 00 ЗЕ 00 
$^FF CO FF CO FF CO 
(8, 8) 

); 


00 00 01 01 00 00 01 
00 00 01 05 00 00 01 


locked, preload) ( 

SF 00 40 80 80 40 90 
40 80 ЗЕ 00 ЗЕ 00 ЗЕ 
SF 00 TF 80 FF CO FF 
TF 80 3F 00 3F 00 3F 


locked, preload) ( 

ЗЕ 00 40 80 80 40 80 
40 80 ЗЕ 00 ЗЕ 00 ЗЕ 
SF 00 TF 80 FF CO FF 
7F 80 3F 00 3F 00 3F 


resource ‘CURS’ (261, locked, preload) ( 


$"3F 00 ЗЕ 00 ЗЕ 00 


JF 00 40 80 80 40 80 
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02 
06 


40 
00 
CÓ 
00 


40 
00 
Ce 
00 


40 


88 60" 
ЗЕ”, 
FF CO" 
ЗЕ”, 


80 60" 
ЗЕ”, 
FF Сй" 
ЗЕ”, 


80 60" 


$"9C 60 88 40 90 40 
ЗЕ 00 ЗЕ 00 ЗЕ 00 
$“FF CØ FF CØ FF CØ 
(8, 8) 


resource ‘CURS’ (260, 
$"3F 00 ЗЕ 00 ЗЕ 00 
$"9C 60 84 40 84 40 
$°ЗЕ 00 ЗЕ 00 ЗЕ 00 
$"FF CO FF CO FF CO 
(8, 8) 


resource 'CURS' (259, 
$^3F 00 ЗЕ 00 ЗЕ 00 
$"9C 60 82 40 80 40 
$^3F 00 ЗЕ 00 ЗЕ 00 
$^FF CO FF (0 FF CO 
(8, 8) 


д 
resource ‘CURS’ (258, 
{УЗЕ 00 ЗЕ 00 ЗЕ 00 
%”ОҒ 60 80 40 80 40 
$"3F 00 ЗЕ 00 ЗЕ 00 
$^FF CØ FF CO FF CO 
(8, 8) 


д 
resource ‘CURS’ (257, 
{ЗЕ 00 ЗЕ 00 ЗЕ 00 
$"9C 60 80 40 80 40 
$?3F 00 ЗЕ 00 ЗЕ 00 
$^FF CO FF CØ FF CO 
(8, 8) 


resource ‘CURS’ (256, 
$"3F 00 ЗЕ 00 ЗЕ 00 
$"9C 60 80 40 80 40 
$"3F 00 ЗЕ 00 ЗЕ 00 
$^FF CO FF CO FF CO 


40 80 ЗЕ 00 ЗЕ 00 3F 00 SF’, 
ЗЕ 00 ТЕ 80 FF CO FF CO FF Сй" 


ТЕ 80 ЗЕ 00 ЗЕ 00 ЗЕ 


locked, preload) ( 

ЗЕ 00 40 80 80 40 80 
40 80 ЗЕ 00 ЗЕ 00 ЗЕ 
ЗЕ 00 ТЕ 80 FF CO FF 
TF 80 ЗЕ 00 ЗЕ 00 3F 


locked, preload) ( 

SF 00 40 80 80 40 80 
40 80 ЗЕ 00 ЗЕ 00 ЗЕ 
SF 00 ТЕ 80 FF CO FF 
TF 88 3F 00 3F 00 3F 


locked, preload) ( 

ЗЕ 00 40 80 80 40 80 
40 80 ЗҒ 00 ЗҒ 00 ЗҒ 
ЗЕ 00 ТЕ 80 FF CO ҒҒ 
TF 80 ЗҒ 00 ЗҒ 00 3F 


locked, preload) ( 

ЗЕ 00 40 80 80 40 81 
40 80 ЗЕ 00 ЗЕ 00 ЗЕ 
ЗЕ 00 ТЕ 80 FF CO ҒҒ 
TF 80 3F 00 3F 00 3F 


locked, preload) ( 

SF 00 40 80 84 40 84 
40 80 3F 00 3F 00 3F 
ЗЕ 00 ТЕ 80 FF CØ FF 
TF 80 3F 00 3F 00 3F 


40 
00 
CO 
00 


40 
00 
cø 
00 


40 
00 
Ce 
00 


40 
00 
Ce 
00 


40 
00 
CB 
00 


ЗЕ”, 


80 60" 
ЗЕ”, 
FF С@" 
ЗЕ”, 


80 60" 
ЗЕ”, 
FF Co” 
ЗЕ”, 


80 60" 
ЗЕ”, 
ЕЕ Сй" 
ЗЕ”, 


82 60" 
ЗЕ”, 
FF Co” 
ЗЕ”, 


84 60" 
ЗЕ”, 
FF Сй" 
ЗЕ”, 


(8, 8) 
); 
Animated Cursors Again 
Erny Tontlinger 
Steinfort, Luxembourg 
Here are some comments to David Stoops’ Animated Cur- 
sors from the December 1988 Letters Column. 
There is an error in the procedure InitWatch. The cursor id 
should be replaced by the cursor handle in the loop this: 
Watch[watchcount] := 


GetCursor (HiWord( longintCWatch[watchcount 1222; 
The correct structure of a ‘acur’ resource is: 
acur = record 
frames: integer; (Number of frames(cursors) ) 
whichWatch : integer; 
Watch : array[1..99] of CursHandle 
( size depends on frames ) 


end; 

Then instead of using a fixed number of eight cursors, use 
Watch .frames, which happens to be eight for the Finder. 

The ‘acur’ and ‘CURS’ resources should be locked, other- 
wise the VBL task runs into troubles with the memory Manager. 
The Finder uses the ‘CURS’ id 4 (classic watch cursor), which in 
the System file is not locked. This cursor is also in ROM, from 
the Mac Plus machines on, so it would be good to set RomMap- 
Insert to mapTrue before calling GetCursor. 

SetUpAS and RestoreAS might not work as expected under 
MultiFinder. The value of А5 should be placed in a position, 
other than CurrentA5 іп low memory globals, where the applica- 
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tion can find it from within the VBL task. See “Programmer’s 
Guide to MultiFinder” (APDA# KMB017) the chapter “The A5 
world/VBL tasks”. 


More Animated Watch Cursors 
Rob Terrell 
Chapel Hill, NC 

In the December issue, you printed a letter that showed how 
to animate the watch cursor as a VBL task, which I thought was 
strange since a few issues back you printed another letter that 
gave a very good reason not to: a VBL task can goon and on while 
the application has crashed, and the poor user will be stuck 
thinking everything is okay. 

A better way to implement the animated watch is through a 
unit that just takes a single call to increment the cursor. Support 
for this exists in TML Pascal II; for those not fortunate as to own 
TML, here’s a unit that does essentially the same thing: 


Unit WetchItSpin; 

(*Make sure you have copied the ‘acur’ and ‘CURS’ *) 
(* resources from the Finder into your application *) 
(* ResEdit is quite handy for this *) 


Interface 
Uses MemTypes, QuickDraw, OSintf, Toolintf; 


type 
aCur = record 
whichWatch : longint; 
watch : array[1..8] of CursHandle; 
end; 
acurPtr = ^ acur; 
acurHandle = ^acurPtr; 
var 
currentWatch : integer; 
WatchList : acurHandle; 


Procedure InitSpinner; 
Procedure SpinWatch; 


Inplenentation 
Procedure InitSpinner; 


: integer; 
begin 
watchList := acurHandle(GetResource('acur ^,02); 
with watchList^^ do begin 
for count := 1 to 8 do 
Watch[count] := GetCursorCHiWordClongint( 
Watchlcount 122); 
whichWatch := £; 


end; 
end; (* InitSpinner *) 


Procedure SpinWatch; 
begin 
with WetchList^^ do begin 
1? whichWatch >= 8 then whichWatch := 1 
else whichWatch := whichWatch + 1; 
SetCursor (Watch[whichWatch ]**); 
end, 
end; (* SpinWatch *) 
end. 
Most of this code was simply taken from David Stoops’ 


letter. However, to use this, you call InitSpinner when you 
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initialize everything else at the beginning of your program; then 
you call SpinWatch each time through a loop or time-consuming 
process to increment it. Not quite as nice as having a VBL take 
care of it, but this way, if you crash, the hands will stop. 
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FORTRAN Math Libraries 
Michael M. J. Tracy 
Pittstown, NJ 

I am writing in response to Tatsuhito Koya’s request (Feb 
1989, Vol. 5 No. 2) for information on FORTRAN math libraries 
that will run on the Mac. There is an excellent book out called 
‘Numerical Recipes: The Art of Scientific Computing’ by Wil- 
liam H. Press, Brian P. Flannery, Saul A. Teukolsky & William 
T. Vetterling (Cambridge University Press, ISBN 0 521 30811 
9). I refer to this book infinitely more often than “Inside Macin- 
tosh’ when writing scientific applications on the Mac (and it’s 
cheaper too, about $35 hard cover). The book provides the source 
code for over 200 subroutines. Its real value to the user, however, 
is in the eloquent and intelligent discussion of the principles 
underlying each algorithm, explaining the strengths and weak- 
nesses, and usually providing alternative algorithms so that the 
cautious user can cross check results. I have learned a lot from 
this book. Listing from the contents page, the book covers; 
solution of linear algebraic equations; interpolation and extrapo- 
lation; integration of functions; evaluation of functions; special 
functions; random numbers; sorting; root finding and non-linear 
sets of equations; minimization and maximization of functions; 
eigensystems; fourier transform spectral methods; statistical 
description of data; modeling of data; integration of ordinary 
differential equations; two point boundary value problems; par- 
tial differential equations. There are two versions of the book. 
The original edition gave the subroutine listings in both FOR- 
TRAN and Pascal. By popular demand, a second version was 
released which presents the C source code listings (written 
somewhat from the perspective of a FORTRAN programmer 
who wishes to convert to C, and provides structures and functions 
for handling complex numbers). Macintosh compatible disks 
containing the source code are also available from the publishers. 

All FORTRAN subroutines that I have used work well, and 
have compiled without any problems under both MacFortran and 
Language Systems Fortran. Some subroutines, however, need to 
have the 'SAVE' statement added at the beginning (as required 
by the ANSI 77 FORTRAN standard) if local variables need to 
be preserved between subroutine calls, such as in the random 
number generators. 


Author Incentive Program Correction 
Kirk Chase 
Anaheim, CA 
In the December '89 MacTutor, we made a correction on the 
Author Incentive Program initiated by Apple. Additional reim- 
bursement is ONLY FOR APPLE EMPLOYEES. Those not 
employed by Apple DO NOT QUALIFY. We are sorry for any 
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confusion that may have resulted over this and hope this clears up 
any mistaken notions. If you are with Apple, and if you want 
more information, please contact Stacey Farmer in public rela- 
tions, who is now incharge of the program, for more information. 
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Aranda Revolutionizes Software Development 
David E. Smith 
Editor & Publisher 

The microelectronics industry uses CAD software to de- 
velop complex IC’s automatically through software. Now, 
thanks to a new software development utility called Aranda, 
software development will benefit from the same type of design 
automation that IC designers have enjoyed for several years. 

Aranda is a compiler specific utility that opens and reads 
computer source code text files, parses the language syntax and 
builds an interactive symbolic flow chart representation that is 
linked by hypertext to the original program listing. Edit changes 
to either the graphical flow chart representation or the source 
code itself results in the other representation being updated 
automatically. Code can be cut and pasted in symbolic form, 
detail hidden or expanded, call links between modules called out 
and many other design tools used to facilitate and automate the 
software design process. But the important feature any program- 
mer will love is that finally, software documentation and flow 
charts can be created after the fact and linked dynamically to the 
code so that the documentation and the code stay up to date at all 
times. Have a strange program you don’t understand or didn’t 
write, but are required to maintain or upgrade? No problem! Just 
run it through Aranda and the entire program structure, design 
and variables will be extracted and symbolically and graphically 
represented. The authors ran the entire MacApp source code 
through Aranda and out came a giant flow chart of the entire 
MacApp module tree in just a few seconds! Aranda can be used 
in a top-down software design environment from the beginning 
of the design cycle, as an expert system editor, or in bottoms-up 
redesign to extract the program structure and facilitate upgrades 
and maintenance of programs already written. Modules can be 
documented by appending interactive notes to the source code or 
equivalent flow charts, and the notes travel with the modules as 
they are cut and pasted into new programs. Now the dreary 
process of documenting and specifying the software design is 
automated and extracted from the source code itself, leaving the 
programmer free to do the fun stuff: writing code, not documen- 
tation. 

Aranda isa product of Soft-SET Technologies of Vancouver 
in Canada and benefits from University work that allows the 
authors to generate new parsing engines for different compilers 
in a matter of days. MPW Pascal, Lightspeed Pascal and C 
versions are going into beta site testing now with Cobol, PL1 and 
C++ versions to follow. Pricing and product availability have not 
yet been finalized, but people who should know inside Apple are 
already drooling over the prospect of beta testing this product, 
something Apple normally never does for third party software. 
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For more information, contact Bill Campbell at (604) 734-1622 
or AppleLink CDA 0380. MacTutor will be using this product as 
it becomes available, and we will have much more on this when 
we see the beta version, which should be shorty after Apple’s 
Developer Conference, where Aranda will be introduced for the 
first time. 


More Math Libraries 
Bob Estes 
Somerville, MA 

I'm writing in response to T. Koya's request for information 
on Fortran math libraries in the February issue. The source code 
to all the routines in Numerical Recipes: The Art of Scientific 
Computing (Press, et al.) is available on Mac disks from Cambr- 
idge University Press, Order Dept., 510 North Avenue, New 
Rochelle, NY 10801 for $39.95. The book, which has to be 
purchased separately of course, explains the routines and con- 
tains references to other work. You'd probably need the book to 
use the routines, but it's a valuable (700+ pages) reference 
anyway. The source code is available in Fortran, Pascal, and C. 
The C version has its own book and follows the quirks of the 
authors, who don't like C very much for scientific computing. 
You need to specify that you want the Mac disks. The code 
should compile with any compiler. 


More on Numerical Library 
C. H. Friend 
Watford, Herts, England 

I assume the inquiry from Tatsuhito Koya in the MacTutor 
February 1989 Letters refers to replacements for the routines 
commonly supplied with most mainframe systems for perform- 
ing mathematical tasks and special functions (usually NAG in the 
U.K.). Such a library is available in source code form as 
“Numerical Recipes” from Cambridge University Press. 

Now that it is possible to get disks of these books in 
Macintosh format, here’s a summary: 

Numerical Recipes is a practical reference and textbook for 
anyone doing numerical analysis. The authors provide the 
techniques and programs needed, also advice on which methods 
should be used for solving problems, with practical emphasis on 
proven algorithms. 

The reader is assumed to be mathematically literate and 
familiar with one of the languages used, but no prior experience 
with numerical analysis is required. 

Books: 

Numerical Recipes - the original in Fortran, with Pascal 
source in an appendix. Disks for either language available 
separately. 

Numerical Recipes in C - the follow up to the above. Exactly 
the same coverage, with C source code. Disks of the book 
available. 

Chapters in the books: 

1) Programming style, conventions, accuracy. 

2) Linear equations. 

3) Interpolation and extrapolation. 

4) Integration of functions. 
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5) Evaluation of functions. 

6) Special functions (Bessel, probability, etc.). 
7) Random numbers. 

8) Sorting. 

9) Root finding and nonlinear equations. 

10) Minimization or maximization of functions. 
11) Eigensystems. 

12) Fourier transform spectral methods. 

13) Statistical description of data. 

14) Modeling of data. 

15) Integration of ordinary differential equations. 
16) Two-point boundary value problems. 

17) Partial differential equations. 


The original book was written in Fortran, with Pascal source 
asan appendix. The translation was done by machine, so some 
of the code might look odd to the experienced Pascal program- 
mers. A project to improve this is under way, and should result 
in a separate Pascal edition later. Fortran source is F77 standard. 
Pascal is ISO standard, though the Mac disks have been altered 
slightly to declare “longint” where it matters and to show “in- 
clude” files. If your Pascal uses units, the routines will all have 
to be amended accordingly, but this is not difficult. 

The versions in the C book are a complete rewrite, and the 
introductory chapter includes some helpful discussion of C 
programming for numerical purposes. The C disks are in 
MSDOS format only, a Mac version is not currently listed. 

There is also a parallel set of books and disks titled "Numeri- 
cal Recipes Examples” which contain short demonstration pro- 
grams and some data files showing the use of these routines. 
These are quite useful for testing compilers, etc. 

Numerical Recipes - The Art of Scientific Programming: W. 
Press, B.P. Flannery, S. Teukolsky, W.T. Vetterling, Cambridge 
University Press 1986. 0-521-30811-9 818pp. 

Numerical Recipes in C: W. Press, B.P. Flannery, S. 
Teukolsky, W.T. Vetterling, Cambridge University Press 1988. 
0-521-35465-X 768pp. 

Numerical Recipes Example Books: in UCSD-Pascal, 0- 
521-30956-5; Fortran-77, 0-521-31330-9; or C, 0-521-35746-2 

Recipe Disks: 

0-521-35466-8 (C) 5.25 in. MSDOS. 

0-521-35501-X (Pascal) 3.5 in. Macintosh. 

0-521-35469-2 (Fortran-77) 3.5 in. Macintosh. 

Example Disks: 

0-521-35467-6 (C) 5.25 in. MSDOS. 

0-521-35502-8 (Pascal) 3.5 in. Macintosh. 

0-521-35468-4 (Fortran-77) 3.5 in. Macintosh. 

[Well, there seems to be enough information to get a handle 
on some math libraries. A special thanks to our readers who are 
always on top of things. -ed] 
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Corrections 
Don Koscheka 
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Arthur Young М0735 

Joe,your article on adding windows to XCMDs was infor- 
mative and, for the most part, well written. Your discussion of 
scroll bars needs clarification. You state that using ScrollRect to 
scroll a window is not the preferred approach because the 
window will not get redrawn until update time. This is not true. 
While Inside Macintosh does imply that you should pass the 
UpdateRgn of the current window to ScrollRect so that the 
vacated area gets accumulated into the window's invalrgn, this is 
not strictly necessary. Consider the following code fragment: 


Procedure TrackScrollC theControl : controlHandle; thePart : 


INTEGER 2; 
VAR 
TempRgn : Region; 
tempRect : Rect; 
dh, dv : INTEGER; 
BEGIN 
(*** determine what part of the control we’re in... ***) 


(*** and set dh, dv accordingly xxx) 


(%%% now scroll the scrollable part of the window ***) 
tempRect := theWindowsScrollablearea; 
TempRgn := newRgn; 


ScrollRect := (С tempRect, dh, dv, tempRgn 2; 
SetClipC tempRgn ); 


(*** call whatever routine draws window contents | ***) 
Redraw. Тһе Window; 


DisposeRgn( tempRgn 2; 
END; 


This code has the advantage of requiring only enough extra 
memory to store the vacated region. Moreover, the novice 
programmer need not write any special screen drawing code. 
Whatever code is used to draw at update time can be called 
directly to redraw the window at scroll time. Since the window 
isclipped to only the vacated region, this approach results in fast, 
smooth scrolling. 

The more experienced user can query the region to deter- 
mine exactly which rectangle to update so that the application 
draws only what will be displayed in the vacated rectangle. This 
is useful in applications like word processors where much of the 
update time is spent calculating where things need to go on the 
Screen. 

Another interesting consideration is the possibility of creat- 
ing universal scroll bars. We accomplished this by having track 
scroll operate on a "scroll record" that keeps track of all appro- 
priate information relating to a given scroll bar. One of the fields 
passed to the scroll record is the address of the routine to call in 
lieu of *Redraw. the Window" in the above example. The result 
is quite satisfactory: one pair of scroll bars can be made to behave 
consistently regardless of the number of window variations in a 
given application. 

Thanks for the bent ear. Good luck at Apple (as a six-year 
veteran, I can tell you that it's a great place to work...) 


CDEF Corrections 
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Kirk Chase 
Anaheim, CA 
It was brought up to my attention of another way to include 
CDEFs for debugging purposes. James Plamondon, from Aba- 
cus Concepts, pointed out a better, more legal (7), way of setting 
the contriDefProc field of the control record. 


const 
JMP. Instruction = $4EF9; 


type 
JumpRec = record 
instruction 
function : Ptr; 
end; (JumpRec) 


integer; 


JumpPtr = ^JumpRec; 
JumpHd] = ^JumpPtr; 


var 
cdef Jump : JumpHdl; 
сігінді : ControlHendle; 


begin ( Open.Example Window) 
(allocate and initialize jump record) 
cdef Jump := JunpHd1CNewHandleCs izeof (JumpRec))); 
cdef Jump^^ . instruction := JMP. Instruction; 
cdef Jump^^ .function := myCDEFProc; 
(this ends initializing the jump record) 


| (get the control record) 
CtrlHdl := GetNewControl(ButtonID, MyWindow); 


| (Set the contr]DefProc) 
CtrlHdl^*.contrlDefProc := Handle(cdef Jump); 


end; 


After diving into the tech notes, I also found what James 
already knew. James also mentions that the control definition 
proc should be locked by keeping it in code segment 1. 

I appreciate James Plamondon help. The method I gave was 
essentially for prototyping controls. This made development 
time faster since you could bypass the Compile, ResEdit, Com- 
pile, Frustration loop. I hope Abacus realizes the asset James 
Plamondon is. Thanks A Bunch. 
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Font Tool 

Fabien Samuel 

Paris, France 
As always I read the March issue of your magazine with 
pleasure and interest. I would like to share a comment about 
Randy Leonard's article, “How To Write a Font Tool for MPW”. 
To start with, all my congratulations for giving a very clear 
presentation of the matter. I think anybody who reads the article 
now has all the material to easily start writing his own MPW 
tools. I just have acomment about the use of SetResLoad(false): 
as stated in IM, you should SetResLoad(true) as soon as possible 
after calling SetResLoad(false), or you may be asking for trouble. 
Although there is no problem in Randy’s program if it has a 
normal exit, it seems SetResLoad(true) will not be called when 
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the program terminates on an error condition, and this might be 


a problem. 


It appears the only call in the program that might trigger 
Resource loading is GetFNum, so I would personally bracket this 
call with SetResLoad(false) and SetResLoad(true). In that case 
SetResLoad(true) isn't even needed, because GetFNum auto- 
matically calls it before returning (IM I - 223). 


Resource Fork Problem 
Paul Onstad 
St. Paul, MN 

I enjoy your articles of Pascal code but have never come 
across an example which would lead me out of the problem that 
has stopped my application dead in its tracks. 

l. I wish to maintain data in both forks of an applications 
HFS data file. 

2. HFS provides only one Resource Manager call which 
considers the location of the file for subsequent resource calls, 
i.e., OpenRFPerm. 

3. However, when the user performs a “Save” or “Save 
as...” the existing file must be erased with FSDelete. Create then 
follows to create both forks of the file and the revised data is 
written to the data fork. The previous resource fork data is 
temporarily saved in memory by the application. The resource 
fork of the new file is now empty. 

4. After the new data fork has been filled. A call to 
OpenRF Perm is made to open the empty resource fork with the 
intention of using AddResource to place the memory-saved 
resource data back into the revised file. But, OpenRFPerm 
returns an unsuccessful “-1” because of ResError -39 (logical eof 
encountered on the empty resource fork). 

Without a valid refNum from OpenRFPerm there appears to 
be no way to communicate back to the application the location 
(folder, etc.) in which the resource data should be restored on 
disk. The existing refNum was lost because the resource fork had 
to be closed before FSDelete—otherwise the file was “busy” and 
could not be deleted. 

Additional (if of some use): DetachResource was used just 
before the file was erased in order to hold the resource data in 
memory while the actual resource (and data) file was deleted. 

If you can provide any examples or information, it would 
greatly be appreciated. 


MIDI Problems 
John Kaplan 
Chicago, IL 

I have been following your articles in MacTutor for some 
time, but have only recently been able to try your MIDI routines. 
I was hoping you wouldn’t mind a few comments and questions 
that came up for me as I worked. 

First, I know your code was meant for the MDS assembler 
and LSP version 1, but I was using MPW for assembly, and had 
to use LSP version 2. (Version 1 cannot link MPW object files.) 
I found that LSP v2 would not accept an MPW object file with 
DC's in it so I declared all the variables as IMPORT's in the 
assembler, and as variables of corresponding types in the LSP 
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interface file. I didn’t really understand why people objected to 
the use of A5 variables in the first place (since if your going to use 
MIDI in an application you’re going to have to have space for 
your data somewhere anyway...) but that’s not the point. The 
point is that after framing everything in PROC and ENDPROC 
directives for MPW and moving the blocks around to avoid 
forward references, the whole thing compiled and linked fine. 
The only other thing worth mentioning is that MPW assumes 
when a variable is imported that it is referenced through A5, so 
there are no explicit A5 references for the variables. (You 
probably know all this already, but I mentioned it just in case.) 

The next snag I ran into was in testing the routines in LSP I 
wrote a little program that writes incoming MIDI information in 
the LSP text window. This was a big mistake, as LSP v2 seems 
to reserve the right to move your code around in memory as it 
calls graphic operations to update it's text window. After the ten 
or fifteen crashes it took me to figure this out, I rewrote my code 
so I made my own window, and drew the MIDI information in 
with drawstring. (And locked the CODE resource for the LSP 
project in ResEdit, just to be on the safe side.) Finally RXMIDIA 
worked like a charm. 

ThenI wrote a simple sequence in my test program that sends 
a note on, then a note off for the same note. This just doesn't 
work, and try as I might, I can't find what's wrong. I’ve been over 
my code 5 times and can't find a typing mistake, and I don't have 
the expertise in interrupts or serial chips to know exactly what's 
going on to debug it. I was thinking there might be another 
compatibility problem with LSP v2, ora problem with porting the 
assembly code from MDS to MPS that I don't know about. I was 
hoping you could provide some guidance. I am including all 
relevant code I used. Of course, if it’s too much trouble to slog 
through all my code to find bugs, any hint you could give me 
would be greatly appreciated—even so basic as how to start 
figuring out what’s wrong myself (chip manuals and the like?). 
(By the way, the hardware I used was a Mac Plus with both a 
Southworth Jambox 4 and an Assimitation MIDI Conductor. 
When I tried TxMIDIA, I got no light on the Jambox panel, no 
response from my synthesizer, and no message on my Yamaha 
MEP4 MIDI monitor—meaning either no recognizable message 
was sent or no message at all.) 

Offending code: 


outmidi := 90092; 
txnidiaCoutmidi 2; 
outmidi := $003C; 
txmidiaCoutmidi); 
outnidi := 90040; 
txnidiaCoutmidi); 


while button do 
while not button do 


while button do 


д 


outmidi := $0082; 

txnidiaCoutmidi); 

outmidi := $003C; 
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txmidiaCoutmidi); 
outmidi := $0040; 
txmidiaCoutmidi); 


[Not being a MIDI expert myself, I'll leave this up to any 
MIDI experts out there. But Kirk Austin did an update to his 
MIDI routines for an article in May 1989. After a quick look, I 
did notice a couple differences between the code you sent in and 
Kirk’s latest version. Kirk’s latest MIDI code wasn’t published 
due to space limitations. The code is on the source code disk 
(#44) if you wish to order it. —Ed.] 


Powerful Math Libraries Available With 
Language Systems FORTRAN 
Drew Steis 
Herndon, VA 
Language Systems Corporation announced that powerful 
math libraries from the Numerical Algorithms Group, Inc. 
(NAG) are now available for use with Language Systems FOR- 
TRAN. The mathematical library of scientific and engineering 
subroutines has not been available on the Macintosh until now. 


“NAG is a well-known international producer of scientific 
and engineering subroutines for supercomputers, mainframes 
and high-end workstations,” said Rich Norling, chairman of 
Language Systems Corporation. “Now, for the first time, Macin- 
tosh II users will be able to access the same algorithms used on 
supercomputers. NAG has made 172 of the most frequently used 
subroutines available in one package for the Macintosh II. This 
is a substantial portion of the NAG FORTRAN Library and 
provides broad coverage of the principal areas of mathematics 
and statistics. 

Karl Knapp, Technical Manager of NAG, called the availa- 
bility of the NAG Workstation Library for Language Systems 
FORTRAN on the Macintosh II “a significant development, 
particularly for engineers who find themselves coding mathe- 
matical formulas over and over again from scratch. The library 
should free them up to get on with their real work. 

The NAG Workstation Library offers subroutines for a 
wide range of mathematical applications including matrix opera- 
tions, optimization, linear algebra, time series analysis and many 
others. The software is of particular value in projects for aero- 
space, energy production, chemical manufacturing, electronic 
design, and other areas where advanced mathematics are re- 
quired. | 

Language Systems FORTRAN was the first FORTRAN 
compiler to be based in the Macintosh Programmers Workshop 
(MPW). The compiler is full ANSI Standard FORTRAN 77 and 
has the most VAX-compatible extensions on the Macintosh. It 
has the full capabilities of the Standard Apple Numeric Environ- 
ment (SANETM), Apple Computer's implementation of IEEE 
Standard 754 for Binary Floating-Point Arithmetic. 

Language Systems FORTRAN Version 1.2.1 can be ac- 
quired from APDA. The NAG Workstation Library can be 
obtained from Numerical Algorithms Group, Inc. 1400 Opus 
Place Suite 200, Downers Grove, IL 60515 (312) 971-2337. 
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Another Way To Post Events 
Matthew Snyder 
Fairfleld, CA 

In reference to Joel McNamara's article in the July issue, 
there's another way to post command key events, but you 
wouldn’t know about it unless you’d read a somewhat obscure 1 
page chapter in Inside Macintosh Vol. IV. PPostEvent posts an 
event just like PostEvent, but it “returns a pointer to the created 
queue entry.” 

Here’s an example of its use. Like Joel, I needed to post an 
event and then fix the modifier field. This is an FKEY I wrote 
because too many times I found myself ina situation (likea dialog 
box) where ordinary paste did not work. Because the command 
and shift keys are down while the FKEY executes, just using 
PostEvent would result in all the posted events being command- 
shifted. 


“ілсінде <EventMgr .h> 
Sinclude «0SUtil.h» 


maint) ( 
long length, offset; 
int index; 
char **tHandle; 
char *tPtr; 
EvQE1Ptr MyEventPtr; 


if CTEGetScrapLen() > Ø) { 
ZeroScrap(); 
аа 


tHandle = (char **) NewHandle(0); 
length = GetScrap(tHandle, ‘TEXT’, &offset); 
if (length > 0) { 
HLock( tHandle); 
tPtr = *tHandle; 
for (index = 0; index < length; іпдех++) ( 
PPostEvent(Cshort) keyDown, Cint) ІРігГіпдех1, &MyEve- 
ntPtr); 
MyEventPtr_»evtQModifiers = Ø; 


) 


DisposHandleCtHandle); 
) 


By the way, I very much liked Joel's sentiment that as 
programmers we can rise above the mere end user; we're not at 
the mercy of the “software gods." It is a good feeling. 


Hex Conversion 
Temple M. Sarles 
Nashua, NH 
Ienjoyed inputting and getting to run the “ADB Demo" for 
LS pascal 2.0 from your volume 5 number 3 in March 1989. 
Programs like these give dabblers like me some necessary insight 
into interfacing with the toolbox and really making things work. 
It was a bit of a disappointment to find in procedure Quer- 
ySystem the line “str1 := concat(‘System Version (must convert 
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to hex) = ‘, str2, chr(13));”. (emphasis added) Well, I did. 
Enclosed find the listing of a test program with the function 
ToHex which accepts a long integer and returns a string repre- 
senting the value in hexadecimal. I think the code with its 
comments pretty well explains itself. There were two surprises. 
I idly tried a negative number, only to get unexpected results. I 
forgot that negative numbers are represented in two's comple- 
ment. An easy solution using the toolbox is presented in lines 21 
& 22. 

Not really solved is the need to make the string of hex digits 
a variable instead of a constant. If Hex Char = 
‘0123456789ABCDE’ is declared as a constant then line 27 (... 
‚ Hex. Char [Work + 1] ...) gets a compile error of “Too many 
indices are being applied to a variable or expression.” The reason 
for this is not clear, but making it a string variable works well 
enough. 

To apply this to ADB Demo, add function ToHex to 
MyADBStuff in the IMPLEMENTATION section ahead of 
procedure QuerySystem. In QuerySystem, replace the lines: 


NunToStr ing(LongInt( theWor1d.systemVersion), str2, chr(13)); 
strl := concat( ‘System Version (must convert to hex) = 2 


str2, chr(13)); 
with: 


str2 := ToHexCLongInt(theWord.systemVersion)); (convert to 


hex string) 
str2 := concat(copy(str2, 1, length(str2) - 2), 
'.', copyCstr2, length(str2) - 1, 2)); (put in period) 
stri :- concat( ‘System Version = ', str2, chr( 132); 


Appropriate credit should be given to Think Tech- 
nology for their excellent implementation of Pascal and espe- 
cially for their outstanding development environment (DEC & 
Apollo could take lessons). 


program Test; {Just a place to try things out) 


var 
T1: integer; (The value as an integer) 
T2: string; (What it looks like as a string) 


function ToHex (Number In: LongInt): string; (This 
does the job) 
var 
Accumulate: string; (I never work into return value) 
Hex_Char: string; (The set of Hexadecimal digits) 
Shift: Integer; (Offset into the LongInt) 
Suppress_Zero: boolean; 
(A switch to suppress leading zeroes) 
Work: LongInt; (The clipped byte from the Number In) 


begin 
Accumulate := '//; (Start with a blank string) 
Hex_Char := “0123456789АВСОЕҒ”; 
(Somehow this doesn’t work as a Const) 
Suppress Zero := True; 
(To start with suppress leading zeroes) 


(First take care of sign bit, dispose of two’s complement ) 
( end then deal with short three bit high-order hex number) 


if BitTstCGNumber In, Ø) then 
begin 
Accumulate := '-^; 


(The sign bit is set!) 
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Number_In := BitNot(Number_In); theBitMap-bbounds = *theRect; 
(Two’s Complement cleared) 


Number_In := Number_In + $1 if (MemErrorC) == noErr) 
(It’s always one shy - back to DP 101) return(theBi tMap-» baseAddr ); 
end; return(NULL); 
Work := BitShiftCNumber_In, 1); 
„(Bang to left - IM/I-472) 
Work := BitShiftCWork, -29); RectToo1l.Filled(where,workRect) 
(Back to right - IM/I-472) Point where; 
if Work > 0 then Rect *workRect; 
Accumulate := concatCAccumulate, Hex_Char (Work + 11); ( 
GrafPtr workPort; 
Shift := 4; (Start with bit 5 - the 2nd digitd) BitMap workBits; 
repeat (Now a loop for the other 7 digitd) PenStateworkState; 
Work := BitShift(Number In, shift); BitMap oldBits, tempBits; 
(Bang to left - IM/I-472) Rect tempRect, theRect, aRect; 
Work := BitShift(Work, -28); Point newLoc,pivot; 
(Back to right - IM/I-472) long position; 
1f Suppress_Zero then 
if Work > 0 then (The beginning of what we want) GetPort(&workPort); 
begin workBits = workPort-portBits; 
Suppress_Zero := False; 
(A digit - No more leading zeroes} 1f (NewBitMap(&oldBits,workRect) == NULL) 
Accumulate := concatCAccumulate, Hex—Char (Work + return; 
1)) а C (NewBi tMap(&tempBits,workRect) == NULL) 
en 
else (Don’t do anything! !} DisposPtr(oldBits.baseAddr ); 
else return; 
Accumulate := concat(Accumulate, Hex_Char {Work + 11); 
Shift := Shift + 4; (Move over one byte) 
until Shift = 32; (Bit 33 is out of bounds) CopyB i tsC&workBi ts, &oldBits, workRect, workRect, srcCopy, NULL); 
ToHex := Accumulate (Put the result into return value) tempRect = *workRect; 
end; (of function ToHex) tempRect.right = tempRect.right + 1; 
tempRect.bottom = tempRect.bottom + 1; 
begin 
Т1 := 1538; (А famous number now-a-daus) GetPenStateC&workState); 
T2 := ToHexCLongInt(T12); (Let's see what it is) PenNormal(); 


PenSize(workState.pnSize.h, workState.pnSize.v); 
(The next line inserts the period needed to make 
theWorld.systemVersion human readable) pivot = newLoc = where; 
SetRect(&theRect, where .h, where.v, where .h,where.v); 
T2 := concat(copy(T2, 1, length(T2) - 2), ‘.’, copy(CT2, 


length(T2) - 1, 222; while (Button()) ( 
writelnC'T1 = ', ТІ, ': T2 = ', T2) GetMouseC&newLoc?; 
end. (of program Test) position = PinRect(&tempRect,newLoc); 


newLoc.v = HiWord(position); 
newLoc.h = LoWord(position); 


Fill Rectangle Tool if C!EqualPt(newLoc,where)) 
Kevin Parichan ( 
Reedley, CA Pt2RectCnewLoc,pivot,&theRect); 
қ i Pt2Rect(where,pivot,&aRect); 
| In the article I wrote showing how to do the Spray Can and Un ionRectC&theRect , keRect, kaRect); 
Paint Bucket tools I mentioned that there was a unit on GEnie that CopyBitsC&oldBits, &tempBi ts, workRect ,workRect , srcCopy, NULL); 
implemented these and other tools. That unit is no longer SetPor tBi ts(&tempBi ts); 
аы I thought that I ld give away the source for the FillRect(&theRect, workState .рпРаї); 
available, so 1 thoug wou’ E ушез! FrameRect(&theRect); 
standard filled rectangle tool. I rewrote the code in C so as to SetPortBitsC&workBits); 
show that I don't play favorites. With the routine given as is, you at 222. ts, &workBits,kaRect,kaRect,srcCopu,NULL ), 
can easily modify it for ovals and round rectangles, filled or not. ) с. 
The routine uses the current grafport to get the fill pattern and the ) 


i . Enjoy. 
widths for the frame. Enjoy DisposPtr( tempBi ts .baseAddr ); 


DisposPtrColdBits.baseAddr); 


Sdef ine NULL ØL SetPenState(&workState); 
Ptr NewBitMap( theBi tMap, theRect) ) 
BitMap *theBitMəp; 
Rect  *theRect, Volume 5, Number 11 


m ер ош = ((theRect-bright - theRect-»left + Apple Introduces Two New Macs 


theBitMap->baseAddr = NewPtr(theBitMap->rowBytes * (th- Apple Computer introduced the Macintosh Portable and the 
eRect-»bottom - theRect-) top)); 
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Mac IIci at another fancy roll out at Universal Studios last week. 
In much the same fashion as the Mac II introduction, Apple 
invited the press and important industry representatives to hear 
John Sculley pitch his new toys and Jean-Louis Gassée attempt 
to assemble the portable from scratch. Fortunately it went to- 
gether perfectly and we all cheered when he turned on the power 
and up came “Ta Da!” on the screen. The usual visual effects 
were there; laser beams, clouds of smoke, Macintoshes rising 
majestically out of the stage like granite monuments of progress. 
Everyone was properly impressed. There was even a fan club of 
school children wearing Macintosh shirts to stand up and cheer. 
I went with a very pessimistic attitude, especially about the 
portable, but I came away from it very upbeat about both 
machines. I think Apple has done a good job with these two 
products, even if the hoopla at the Universal Studios is wearing 
kind of thin. 

The Macintosh Portable 

If you were expecting a laptop, the portable will be a 
disappointment. My friend Jim Fitzsimmons of Mac America 
took one look at the portable and promptly went out and bought 
one of the new Toshiba Dynabook laptops. He wanted a more 
powerful version of a Radio Shack 100 laptop. The portable 
Macintosh may not be a laptop, but neither is it a transportable 
either. It is typical of many of the Japanese PC portables in size 
and weight. The portable weighs 16 pounds with a 40 meg hard 
disk, floppy disk and the lead-acid battery. The retail price of the 
portable including hard disk is $6500. The developer price is 
about half that amount. The look of the machine is very similar 
to the high end Toshiba portables except that the Mac portable 
has a keypad/track ball option next to the keyboard, making ita 
bit wider than other PC portables. 

Battery is Design Key 

The key to understanding the portable is the design decision 
made by someone at Apple that the portable must be a fully 
functional Macintosh on battery power alone. Which raises the 
question of how many portable PC users actually use their 
computers on battery power alone? Since the running time of 
most portable computers using NiCad batteries is only one or two 
hours, does anyone really use their computers on batteries? If that 
is the number one design criteria, then you need something other 
than NiCad to get more time from the machine. Hence the 
decision to go with a lead-acid battery. The Mac portable runs a 
true 6 to 12 hours of continuous use without re-charging and can 
be re-charged overnight (3 hours actually). Because the dis- 
charge rate is slow and even, sophisticated power monitoring and 
shut-down procedures can be implemented, guaranteeing the 
user never loses data. The Mac has a nine volt battery backed-up 
CMOS RAM as well as a power monitor desk accessory with 
suitable alarms. And the battery can be replaced with the power 
on without losing anything. The trade-off is size and weight. But 
you get what may be the first battery-powered full-blown PC in 
the world where you can actually do something useful all day 
before re-charging. 

Another trade-off of the battery power requirement is that 
the components must be low power CMOS. However, Motorola 
does not make any of the 68000 family in CMOS except the 
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68000. Hence, the processor, and much of the power of the 
machine is decided for you. The portable has a CMOS version of 
the 68000 because that is the only processor available. To keep 
the machine from being a total wimp, Apple upped the clock 
speed to 16 mHz making it the same clock speed if not the same 
processor as the Mac II and the SE/30. The portable ring about 
twice as fast as an SE, which would be expected by doubling the 
clock speed, but not as fast as an SE/30 or Mac IIcx. The battery 
decision also determines memory configuration. Low power 
means CMOS static RAM chips. But CMOS is a bulky process 
of placing N-channel and P-channel transistors in series 4o form 
inverter pairs and is only available in very low densities. Hence 
Apple is only delivering 1 meg portables which can be expanded 
to2 megs with aplug-in memory card. However, some third party 
vendors are said to be bringing 4 meg CMOS RAM cards to 
market for the portable which would give it a limit of 5 megs. 
From the appearance of the portable’s motherboard, the chip 
density is only 256K by 1 bit per chip. Since the battery takes up 
some bulky space (4 inch height in the rear end), the necessary 
height of the case allows the addition of plug-in cards. Besides 
the memory board, you can plug in a 2400 baud modem card, 
upgraded ROMs, and a single processor direct slot, not compat- 
ible with any other processor direct slot in the Macintosh family 
(naturally). The back end of the portable includes the standard 
Macintosh connectors for Appletalk, SCSI hard disks and the 
ADB bus for the mouse. Since operation on batteries alone 
assumes you are not near an AC outlet and hence not near a desk, 
the portable has a track ball so you can use it on your lap. The 
logic of that decision in light of the fact we already concluded it 
was not a laptop, escapes me. Perhaps the motherboard had a 
fixed width that determined the case size, leaving room for 
something besides the keyboard, so the track ball was added. 
Actually, the track ball, being small in size, is much easier to use 
than other track balls for the Mac that I’ve tried. But I still prefer 
the mouse. I'm pretty sure the width of 15.25 inches and depth of 
14.85 inches means it won't fit exactly on an airline tv tray, the 
only place I can think of where you might use it without a table 
top handy. 

Other Features 

Unlike other portable PC's, the Macintosh portable has a 
readable screen display. Each pixel is controlled by a single 
transistor, resulting in what is called an active matrix LCD 
display, as opposed to a passive display used by other systems. 
In effect, the display is a giant IC. There is no ghosting or cursor 
loss and the graphics response is “just as good as a Macintosh". 
This is probably the biggest achievement for Apple in the 
portable design. It really does not sacrifice anything in the display 
to be portable. The display is bright, easy to read, clear, sharp and 
fast enough for all Mac graphics applications. The trade-off is 
that the yields on the display are probably low, which could affect 
the number of machines Apple can make, and undoubtedly 
expensive, which explains the high price. One potential com- 
plaint is that the screen is not backlit, because of the power drain 
it would cause. But it shouldn’t be needed as the screen is very 
bright and can be viewed at any angle clearly. 

Besides the internal modem card option, an external video 
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adapter option is available that allows monochrome images to be 
sent to either Apple monitors or RGB, NTSC, PAL or SECAM 
standard televisions, videocassette recorders and project de- 
vices. This would make the portable ideal for on-the-road pres- 
entations, seminars and instruction settings. This could be the 
highest demand market for the portable. 

An Alternative Portable 

Suppose you made a few changes in the design criteria. What 
might you get differently? Suppose you assume that no one really 
bothers to use computers on battery power alone so you don’t 
need lead-acid batteries. Now you can build a Grid type Macin- 
tosh portable. With AC power, you can use high density dynamic 
RAM chips and an 68030 processor. Instead of 32 individual 
static RAM chips, you can use simm modules. Instead of a 
specially designed low power 40 meg hard disk, you can use off- 
the-shelf 80 meg hard disks. If you assume a table top is always 
available, you don’t need a track ball. This would cut the width 
from 15 inches to 12 inches and the rear height from 4 inches to 
2.5 inches. The motherboard depth could shrink from higher 
density chips so the depth could go from 14 inches to 11 inches, 
making it just slightly bigger than a piece of paper. Now you have 
a true laptop at around ten pounds, that has the power of a Mac 
IIcx or even a IIci if you bump up the clock speed. All those in 
favor of a smaller, more powerful, non-battery laptop that can run 
MPW and MacApp, raise your hands! 

The Mac lici 

The Mac Ісі is a 25 mHz version of the Mac IIcx. In every 
other respect, it is exactly like the Mac Псх with a couple of 
notable exceptions. The сі includes a video controller on board 
that will drive any of Apple's monitors at a depth of 8 bits per 
pixel. The video RAM is taken from the system RAM. Appar- 
ently at pixel depths of 1, 2 or 4 bits, the on-board video is faster 
than going out over Nubus to an external video card, assuming 
you have at least 2 megs of memory. However, at 8 bits per pixel, 
the memory contention between the video processor and the 
68030 makes the on-board video slower than going out to the 
Nubus. The video supports up to 256 colors or shades of gray on 
the Apple 13 inch color monitor (640 by 870 pixels). 

In addition to the built-in video, the Псі has a slot fora RAM 
cache, although Apple will not announce a cache card until next 
year. The highest performance is achieved by using a Nubus 
video card with a cache card. Performance is said to be 45% 
higher than a Mac IIcx and higher still (up to 75%) using a cache 
card. The RAM in the IIci are 80 nanosecond chips as compared 
to 120 nanosecond chips in the Mac II. The retail price of the IIci 
is $7,000 including a 40 meg hard disk. The developer price is 
about half of that. In comparison to the IIcx, the price differential 
for a 50% performance improvement is only $800 and if you 
consider that includes a video card, the cost only $300, a small 
price for a lot of increased horsepower. If you are going to buy a 
Mac II, there is no point in getting anything other than this new 
Ici. 

New ROMS 

The most notable improvement in the Mac IIci has nothing 
to do with hardware. The Mac Ilci is the first Macintosh to get 
new 32-bit clean ROMs! The memory manager is 32-bit clean 
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and all the ROM code has been optimized for the 68030 proces- 
sor. A lot of the system patches in the system file, including 32- 
bit quickdraw have been moved into ROM, increasing the ROM 
space from 256K to 512K in the Mac Псі. This baby is ready for 
system 7! 

When Apple released the IIcx, the motherboard was com- 
pletely re-worked to give a much more denser design than the 
Mac II. With the IIci, Apple has re-designed the motherboard 
with the addition of five new custom ICs. Once again, Apple has 
shown it's willingness to invest in top quality pc board design. 
The Mac Псі motherboard is a work of art. There are 6 very large 
custom IC designs including the video controller and the memory 
controller, plus the Motorola 68030, and 68882. There are 8 
smaller custom chips, including the SWIM chip (revised woz 
machine disk interface) and sound chip. There are only 32 other 
chips on the board including the 4 ROM chips and all the Nubus 
sockets, RAM sockets, ROM socket and cache socket and still 
the board looks very uncluttered. The Mac IIci is by far the most 
powerful and impressive machine Apple has ever offered and 
certainly should give any PC configuration a run for it's money. 
Apple is stressing the total performance improvement of custom 
hardware design, new ROM coding, system software enhance- 
ments as well as the 25 mHz clock speed to promote the Псі as 
advanced as any of the high end PC designs. Itis obviously aimed 
at the government and University research markets. It even 
includes a parity memory option, apparently needed to satisfy 
government purchase order guidelines that were designed to lock 
federal employees into IBM PC machines. With the advent of the 
superdrive that can read IBM formatted disks, federal employees 
can order Macintoshes directly now. In fact, rumor has it that the 
first two months of production for both the portable and the Mac 
IIci, 10,000 units each, has already been spoken for by Uncle 
Sam! 

Apple's Comments 

So what is Apple saying about it's product line now? Atlast 
John Sculley got off the presentation software kick he has pushed 
at the last two MacWorld Expos and returned to the theme that 
Apple builds computers for individuals that combine consis- 
tency, intuitiveness and ease of use for the way normal people 
work. This is the right message for Apple to be focused on. They 
have won the battle of convincing the world that Macintosh is 
easy to use, and graphically powerful. Now they should be 
pushing that message to milk it for all it's worth, instead of 
backing off looking for the next desktop revolution. In it's 
message to the press, Apple VP's seemed to be returning the 
message back to Apple's roots. Randy Battat, VP of product 
marketing stressed the consistency of the Macintosh interface 
across all it's platforms. The software doesn't change. The user 
interface doesn't change. Only the machine gets faster and more 
responsive or more portable and flexible. This goes to the heart 
of the IBM mess where IBM is investing millions into developing 
OS/2 and the Presentation Manager while ComputerLand deal- 
ers sell MS/DOS 3.3 machines running Windows. Is it any 
wonder IBM has reported third quarter results will be unexpect- 
edly down? 

Brodie Keast, product marketing director, stressed that 
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Apple pays attention to details because it designs for the individ- 
ual, to put the individual in control, making computing tools 
transparent. This message strikes at the heart of the PC confusion 
of trying to configure and set up machines that require device 
drivers, screen drivers, choice of incompatible operating systems 
and windowing systems and make the whole mess work together 
with a variety of dissimilar software applications. Keast points 
out that for Macintosh, integration and detail results in acomplete 
set of Apple and third-party tools that work well together. 
Consistency, compatibility and integrated networking were 
themes further stressed by Kirk Loevner, Don Casey and Mike 
Homer. The message that Apple is sending out is that now 
flexibility and choice can be added without sacrificing consis- 
tency and compatibility. This is the right message for Apple and 
we hope that Apple’s national advertising in 1990 will concen- 
trate on these strengths of the Macintosh design. 

Adobe - Apple - Microsoft Connection 

This year’s Seybold Conference turned into a real shouting 
match as Apple and Microsoft proved they really do love each 
other after all and Adobe’s John Warnock and Steve Job’s tried 
to put the best foot forward at finding themselves the odd men 
out. Justa few months ago, Apple sold it’s 16% interest in Adobe, 
makers of the Postscript standard. Anyone who was at the 
Developer Conference and saw System 7 understood why Apple 
had sold out. Apple wants to be in control of it’s own destiny in 
regards to both it’s imaging and printing technology. By paying 
royalties to Adobe for every LaserWriter that goes out the door, 
Apple was taking a financial beating. And Steve Jobs was giving 
them an emotional beating by pushing Display Postscript on his 
Next machine. Clearly Apple had to make a choice. Either it had 
to go with Display Postscript and lose more control to Adobe, or 
it had to do something about Quickdraw. It chose the latter. The 
new Apple font technology, dubbed Royal, brings screen outline 
fonts to the Macintosh product line. Now Quickdraw can print 
text just as good as Postscript. But it still can't rotate text or place 
texton an arbitrary path. Presumably Apple is hard at work on the 
next generation Quickdraw that will replace Postscript in func- 
tionality. The surprise move at Seybold was that Apple has 
licensed it's Royal outline font technology to Microsoft for 
inclusion in OS/2 and IBM officials have announced that Royal 
is both technically sound and will be present in future versions of 
OS/2, as reported by MacWeek. In return, Microsoft is licensing 
it's own Postscript clone to Apple, thus ending Apple's depend- 
ence on Adobe. It also eliminates 25% of Adobe's gross income 
and Adobe's stock fell dramatically from $23 to $15 on the day 
of the anouncement. 

What this means is that Apple, Microsoft and IBM have all 
agreed on an outline font technology that does not belong to 
Adobe. This leaves the Next machine out in the cold. It makes 
Macintosh and IBM PC's even more compatible in the area of 
typesetting and layout, which strengthens both companies. It 
could also lead to a graphics standard as well if Apple improves 
Quickdraw and eventually licenses that as well as it's font 
technology in the future. We don't expect that to happen, but it 
is clear that Apple and Microsoft are the big winners and Adobe 
and Next the big losers in thisround of corporate hardball. Expect 
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Apple to further drive the nail in the coffin with a future line of 
cheap, Quickdraw laser printers, perhaps even a portable one for 
the Mac portable? Apple must continue to support Postscript of 
course, because Quickdraw is not presently an alternative and 
desktop design and typesetting has become Apple's main market 
advantage. But the writing is on the wall and Apple's direction is 
clear. There will be an improved Quickdraw to go with the 
outline font technology in future Macintosh system software 
releases that will eliminate the need for the slower Postscript 
interpreter. 
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There IS an OOP Book 
James Plamondon 
San Mateo, CA 

Ihave just received and read my copy of the September issue 
of MacTutor, and was pleased to discover that it was up to its 
usual high standards. Unfortunately, I was horrified to see one 
piece of misinformation presented — however unintentionally 
—as fact, when the truth could be of great use to your readership. 

In the article MacOOPs!, by Jean-Denis Muys-Vasovic, on 
page 102, in the first paragraph, the author says that "Algorithms 
+ Data Structures = Programs", by Niklaus Wirth, was the book 
that established the case for structured programming in the 
seventies. This is entirely correct. 

Unfortunately, the author goes on to say that "This technol- 
ogy [OOP] has not yet got its *Algorithms + Data Structures = 
Programs”...’, meaning that there is not yet any single book on 
OOP that explains its concepts, advantages, implementation, and 
so on. This statement has not been true for more than a year. 

Everyone who has an interest in OOP should run — not walk 
— to the nearest computer bookstore and buy a copy of Bertrand 
Meyer’s book, “Object-Oriented Software Construction”, pub- 
lished in 1988 by Prentice Hall (about $40). It is without a doubt 
the most comprehensive, concise, and yet readable book on 
Object-Oriented Design and Programming to date — and I have 
no doubt that it will soon be considered to be as important to the 
success of OOP as Wirth's book was to structured programming. 

Just as Wirth's book explained and made the case for block 
Structuring, strong typing, and functional decomposition, 
Meyer's book explains and makes the case for object-oriented 
design, based on considerations of correctness, robustness, ex- 
tendibility, reusability, and compatibility. Meyer's book, like 
Wirth's, combines the rigorous precision of computer science 
with the practical aspects of software engineering. Wirth used his 
own, new language, Pascal, to present his ideas, because the other 
languages of the time were inadequate. Likewise, Meyer uses his 
own language, Eiffel, to present his ideas, because no other 
existing language so elegantly addresses both the theoretical and 
practical issues of object-oriented design. 

Pascal went on to become one of the major computer 
languages of the seventies and eighties, due to its close associa- 
tion with structured programming. Its commercial use was 
hampered by the fact that it was designed to be a teachin gaid, not 
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a language for software engineering. Eiffel, on the other hand, 
was designed from the first to be a practical tool for the develop- 
ment of commercial software. Its future is unlimited. 

In every discipline, its practitioners struggle for years on the 
fringes of great breakthroughs — gravity, natural selection, 
relativity, plate tectonics — until some author comes along and 
puts it all together. That is what Wirth did for structured 
programming, and that is what Meyer has done for object- 
oriented programming. I was a geologist during the battles that 
led to the acceptance of plate tectonics, so I’ve learned to 
recognize a paradigm shift when I see one. 

If knowledge is power, and the future of programming is 
OOP, then this book will give you the power to control the future 
of programming. Take the day off, grab the company credit card, 
go to the nearest computer bookstore, buy Meyer’s book, and 
don’t listen to another word about OOP until you’re done reading 
it. 

Stop reading this letter! Get moving! Run! 

What, you’re still here? 


Virus? 
George Patall 
APO New York 
I am new to Mac programming and an avid reader of 
MacTutor and need your help regarding Mac viruses and their 
eradication. My system (a Mac II with an 80MB HD) had a bad 
case of the “hangs” lasting for 15-20 minutes on bootup and when 
launching applications. I cleared out all the files and reinstalled 
them after examining each one with ResEdit. I installed Vaccine 
on my system and it seems to keep a vigilant eye on any attempts 
to add additional CODE resources. It warns me and asks for the 
usual permission to let it add or deny access to the CODE 
resource. 
However running LS Pascal 2.0, it asks for permission with 


the usual message for every source file I try to add to a project. 
I launched ResEdit and examined my System Folder for any 
telltale signs of Scores or nVIR viruses following Max Rochlin’s 
instructions (Mousehole Report, MacTutor June 1988). None 
were found! However, the LS Pascal application’ s CODE id=0’s 
eleventh word displays ‘038A’ and the tenth displays 'AEED'. 
According to MaxR this is a sure sign of Scores infection! But 
I could not locate any additional CODE segments corresponding 
to 038A which is two higher than the next, nor atpl id 128, data 
id -4001, inits 6, 10, 17, Desktop and Scores files in the System 
Folder. І checked the master LS Pascal 2.0 disks I got from Think 
and they too display the same anomalies with 4EED and 038A. 
Is the LS Pascal infected, or is it normal code for LS? Do you 
think it is a new strain? It does not seem to spread to other 
applications so far. But I am at a loss as to how to combat this 
other than turning Vaccine off, which I don't want to do knowing 
if it is safe to run LS Pascal. I am stationed in Heidelberg 
Germany and the local Apple reps could not answer anything 
beyond the most elementary questions. 

[LS Pascal adds code resources to its project file each time 
you compile, so naturally Vaccine will intercept the attempt to 
add a code type resource, like CODEs and CDEFs. My copy of 
LS Pascal also contained the same words in CODE 0. I have been 
using VIREX by HJC Software and Vaccine before without a 
hint of virus troubles. A quick call to Symantec said that the jump 
table is beyond that point and those are the words that should be 
there. So my opinion is that you don't have a virus. I would 
suggest your ‘hangs’ are due to INITs. One of them is likely to 
be giving you problems. 

If you are worried about virus problems, may I suggest that 
VIREX or another commercial virus program. It is my under- 
standing that Vaccine is not continually updated as other com- 
mercial programs. -ed] < 
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From: rustyt (Rusty Tucker, Irvine, CA) 

Subject: BitMap to Region 

A while ago I thought that I saw something posted about code 
that will convert an Icon Bitmap into a region. Does any body 
know where I could find this, or have any examples or ideas on 
how to do this? Any help at all will be appreciated!! 

From: emmayche (Mark Hartman, Fullerton, CA) 

Subject: Re: BitMap to Region call 

There exists a BitMapRgn() call from DTS. It’s a (believe it 
or not) separately licensable product. We have a copy; as far as 
I can tell, I can only distribute it with Photon Paint. 

What it does is to convert a BitMap (no PixMaps here) to a 
Region. FAST. What used to take 2 minutes now takes virtually 
no time. Great stuff. Give a call or drop some e-mail if you need 
any more info. 

From: chenette (Philip Chenette, Los Angeles, CA) 

Subject: Double Clicks 

This is probably a silly question, but I can't figure out how to 
detecta double-click of the mouse. I wantto open up a dialog box 
when the user double-clicks on an object, but it seems there's no 
event message for this. What am I missing? (Using LSP 1.11) 
Thanks! 

From: thecloud (Ken Mcleod, La Habra, СА) 

Subject: Re: Double Clicks 

You're right, there's no DbICIikEvt... you need to compare the 
time and location of a mouseUp event with those of the next 
mouseDown event, and if they're sufficiently close, the user 
double-clicked. Read Inside Macintosh Vol. 1, pp 255-56. If 
you're still having trouble, I can dig up some sample source code. 

From: rdclark (Richard Clark, Tustin, CA) 

Subject: Re: Double Clicks 

The mouse isn't supposed to move more than 3 pixels between 
the 2 clicks, otherwise, it's considered a click-and-drag opera- 
tion. Also, looking at the low memory global DoubleTime isn't 
such a good idea, as Apple is discouraging any direct access to the 
low memory globals. Use GetDbiTime() instead. Now for some 
code: 

#def ine abs(x) ((x) >= 0 ? (x) : (00) 
Boolean IsDoubleClick(where) 
Point where; 
( static Point oldLoc; 
static long oldTime = 0; 
long now = TickCount(),; 
Boolean idc; 
idc = FALSE; 
/* First, see if the 2 clicks are close enough in time */ 
if ((now - oldTime) < GetDb1Time()) 
/* They are, so see if they are close enough in space %7 
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if ((abs(where.h - oldLoc.h) <= 3) && (abs(where.v - 
oldLoc.v) <= 3)) 
idc = TRUE; 
oldTime = now; 
oldLoc = where; 


return idc; ) 

From: emmayche (Mark Hartman, Fullerton, CA) 

Subject: Re: Double Clicks and further checks 

Richard is correct, as far as he goes; however, don’t forget to 
check that the clicks are still within the same screen area (for 
example, the object on which your user will double-click to get 
that dialog). If he’s real close to the edge on the first click, and 
just barely outside on the second click, it shouldn't be considered 
a double-click. 

(I generally set a flag called checkDoubleClick in my main 
dispatch loop which checks the time and object, and let the 
routine which handles the object decide if it was indeed a double- 
click.) 

From: dsa (Dave Stine, Saugus, CA) 

Subject: MPW _RTExit routine 

Just nailed a real weird one. I have a driver which patches the 
ExitToShell trap for applications which open a communications 
session in said driver. This is done because drivers running under 
MultiFinder don’t receive a “goodBye kiss”. 

Well, it would seem that applications written in MPW C don’t 
call the Exit ToShell code in the normal manner; I think that in the 
_RTinit routine, they filch out the current routine in the Exit- 
ToShell trap address, stash this off in some parameter block, and 
it would appear that in. RTExit, they JSR (a0) to this entry point 
directly. 

All of which means that if something patched ExitToShell 
*after* the RTInit routine has run (which is caglled before you 
main() entry is), you patch does not get invoked at program exit 
time. Can anyone confirm this for me, oram I just blowing smoke 
thru my hat? 

From: rdclark (Richard Clark, Tustin, CA) 

Subject: Re: MPW RTExitroutine 

Yes, MPW C is doing something strange with ExitToShellQ, 
and it seems that patching around the trap cannot be done. 
However, if you look at IM II-59, you'll see an "Assembly- 
language note" which implies that ExitToShell() calls Launch(Q). 
(Andaquick test with MacsBug seems to confirm this. However, 
Icouldn't see the “launch” execution under MultiFinder — I had 
to re-run the test under “flat” finder.) I dunno, this stuff sounds 
pretty dangerous. 

From: dsa (Dave Stine, Saugus, CA) 

Subject: Re: MPW . RTExIt routine 

Actually, the only reason I need to have the program come thru 
ExitToShell() is because MultiFlounder doesn't call drivers with 
the "goodBye Kiss" that the normal Finder does. So.... if some 


@ The Best of MacTutor, Vol. 5 


application has a network session open thru my driver, and 
doesn't take care to close said session before exiting, there will 
be some grief Real Soon Afterwards. 

So, the folks at Apple DTS told me to patch ExitToShell() to 
get around this “improvement” that MF made. So I did. And now, 
I find that yet another piece of Apple code has put a ditch in my 
path. 

Yes, your suspicion about ExitToShell calling _Launch is 
correct — in the nominal Finder case. Under MF, things get much 
more hairy. When an application exits, MF must tear down the 
“sub-heap” that was created for the app to run in, and do some 
other funky things. If you want to see the beginnings of how MF 
launches an app, see Goldman's article in Aug. '88 Byte (of all 
places), wherein he describes some of what MF does. This was 
an especially nice article, full of info you simply can’t get from 
DTS, even if you ask. (I did) 

Anyway, I have already hopped around the problem for the 
time being. Thanks for your time. 

From: аба! (Alan Dail, Hampton, VA) 

Subject: Re: MPW _RTExit routine 

Rather than waiting for ExitToShell to be called for you, why 
don’t you just call ExitToShell yourself when your program is 
done? 

From: dsa (Dave Stine, Saugus, CA) 

Subject: Re: MPW __RTExit routine 

‘Cuz my stuff is a driver, which is being used by the application 
which calls _RTExit, which doesn’t сай ExitToShell(). 

Calling ExitToShell() for a client application from a driver 
often result in much sadness. 

From: rdclark (Richard Clark, Tustin, CA) 

Subject: Re: MPW . RTExit routine 

Whoa! 1f you look at the original post, it's the App which is 
supposed to call ExitToShell() — the driver is trying to intercept 
THAT call so it can close itself. 

However, another ugly problem rears its head — many appli- 
cations don't use ExitToShell(). Instead, they simply execute an 
RTS when done, which returns them to a place within the 
Launch() trap (which then returns them to the Finder or what- 
ever). Time to go digging for some other way of shutting things 
down cleanly. 
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From: thecloud (Ken Mcleod, La Habra, CA) 

Subject: ScrollRect() 

I'd like to be able to use ScrollRect to cause one bitmap to 
scroll down *into* a window, as the contents of that window are 
simultaneously scrolling down out of the visRgn. Trouble is, the 
update region gets filled with the port's bkPat (white) by 
ScrollRect, and this results in a “flash of white" before I can get 
the area redrawn. Can anyone point outa strategy for accomplish- 
ing this “smoothly”? I’m currently doing something like this: 

for Ci=1; i <= appropriate_multiple_of_inc; i++) ( 

ScrollRect(&theRect, Ø, inc, myRgnHandle); 

ScrollRect(&enotherRect, Ø, inc, myRgnHandle); 


Drew.Stuff In anotherRect() } 
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but I'm sure I just need someone to kick me in the right 
direction! 

From: rdclark (Richard Clark, Tustin, CA) 

Subject: A kick in the right direction 

Look at the articles by Scott Boyd ("The MacHax Group") 
in the past 2 years of MacTutor — they show how to do some 
pretty weird stuff with off-screen bitmaps and the like, including 
a trick to get rid of the “flash of white" when moving/updating a 
window. 

From: isr (Larry Rosenstein, Cupertino, CA) 

Subject: Re: ScroliRect() 

The best thing to do is to create an offscreen bitmap and use 
CopyBits to draw the bitmap on the screen in its proper position. 
If I understand your application correctly, you want to smoothly 
change from one image to the other. In that case, you would need 
to have the combined image offscreen, and use a series of 
CopyBits calls to draw the appropriate rectangle on the screen. 
(You would start out by copying the entire first image, then most 
of the first and part of the second, etc.) 

CopyBits works the fastest when Quickdraw doesn't have to 
shift every scan line. If you can control the position of the 
window on the screen, then you should make sure that its global 
screen position is a multiple of 16 (or 32 on a Mac II). 

There probably is a way to prevent ScrollRect from erasing 
things, but the resulting effect wouldn't be acceptable either. 
You would notice the delay between the ScrollRect and the 
redraw. 

From: robert (Rob Anthony, Chicago, IL) 

Subject: Macintalk 

Check out APDA (Apple Programmers and Developers 
Assoc., in Renton, WA). They had — in their ‘Curiosity Shoppe’ 
section — the MacinTalk Development Package v. 1.31. It has 
docs and tools for using MacinTalk (they say). I don't have it, so 
Ican't give any personal experience, but the APDA folks should 
be able to answer your questions. Need to be an APDA member 
to order; about $20 a year for that, but well worth it for the Mac 
programmer. 

From: mwatts (Michael Watts, Santa Clara, CA) 

Subject: limit on scroll bar value 

Ні. Iam new to the mouseholeand have spent an informative 
session catching up. There is one question which I need help on 
if someone would be so kind. 

In the app which I am writing, I have to deal with data which 
contains more than 32k points. I want to scroll through this data 
using a scroll bar, however the max value is an integer (opps). 
Even if I write my own control, in IM V 1-333 the upper value for 
the CNTL resource is 2 bytes (not enough). I have kludged a fix 
by breaking the stream into 32k point sections, however this adds 
another control to my window and complexity to the program. 

Does anyone know how to get around this problem, and if so 
how? 

From: thotpolc (Bill Evans, Irvine, CA) 

Subject: Re: limit on scroll bar value 

"Doctor, it hurts when I do this." 

“Don’t do that..." 

Your kludge to break the stream into 32k point sections is a 
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good start. I don’t think the designers of the Mac interface and 
toolbox really anticipated someone scrolling more precisely than 
this. Notice, however, that the scroll bar is between two arrows, 
each of which points away from it. You could use these to scroll 
more precisely. To get the flavor of this, use any word processing 
program to create a document with more than 64k lines. (Proba- 
bly short lines will make the whole thing a little easier.) Then 
scroll back and forth, using all parts of the scroll bar: the thumb 
(which is that funny white box you can slide back and forth with 
your... well, with your thumb), the gray parts of the bar itself, and 
the arrows at each end. In a well-tempered word processor, a 
single click in one of these arrows should move you up or down 
by one line; holding down the mouse in one of these arrows 
should, after a short while, start scanning through the document 
in small increments. Go thou and do likewise.— the Thought 
Police 

From: rdclark (Richard Clark, Tustin, CA) 

Subject: Re: limit on scroll bar value 

There are a couple of ways to take care of your problem: 

1) Redesign the software so that a single click on the down 
arrow moves you down by n points instead of 1 point (where n 
could be 1/4 screen or something.) Some how, I don’t think 
that'll be satisfactory for you. 2) Write a custom control 
definition thatuses something larger than an integer (an unsigned 
integer, maybe?), then avoid using calls like “SetCtlValue” and 
*GetCtl Value". Fortunately, there's a set of options available to 
you in writing a custom control definition that allow you to get 
away without Set/GetCtl Value. The first problem involves drag- 
ging the "thumb" portion of the scroll bar. If you look at IM I- 
331 and I-332, you'll see that you can write a “drag”, "position", 
and “thumb” routine that override the control manager (I suspect 
that the control manager uses the get/set control value calls.) 
These could read your "extended" position information and 
adjust the control accordingly. That leaves a different problem 
— what happens if the user clicks in one of the arrows?? You'll 
need to pass a message to your control to adjust itself by 1. The 
only reasonable way I can think of doing this is to make one of 
your control messages do double duty (you don't want to pick a 
new message number since Apple might decide to use that 
message someday, and that could hurt.) How about calling the 
control definition with a second (third, fourth...) “initCntl” 
message and a special value in the “param” parameter?? Your 
definition could recognize the special value (or the fact that 
you're already initialized) and adjust itself accordingly. 

On second thought, why not just live with a scroll bar 
position which is an approximation of the real position?? After 
all, we won'tbe seeing 33K pixel by 33K pixel screens in the near 
future, so all your extra effort won't mean much on the display. 

From: mwatts (Michael Watts, Santa Clara, CA) 

Subject: Re: limit on scroll bar value 

That is a good suggestion. I was fixating on using the scroll 
bar value as my numerical indicator on where I was in the data 
set. Your suggestion implies I have a position variable which is 
incremented by the scroll step parameter and then position the 
thumb relative to the size of the data set.—a very “thoughtful” 
piece of advice. 
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ps- I still consider this a kludge solution. there should be a 
way to have the value of the scroll bar be a long integer. 

From: rdclark (Richard Clark, Tustin, CA) 

Subject: Re: limit on scroll bar value 

Actually, I like the thought police's answer MUCH better. 
(But I never could resist a good challenge!) 

From: thotpolc (Bill Evans, Irvine, CA) 

Subject: Re: limit on scroll bar value 

rdclark (Richard Clark, Tustin, CA) writes: 

On third thought, if you want exactly what you want without 
kludges, why not throw away the whole idea of part numbers and 
messages doing double duty and custom control definitions, and 
just do the whole durn thang using normal QuickDraw calls? I 
did this once with buttons which I wanted to have a special shape, 
and it was fun! If I ever use scroll bars, I'm going to want the 
thumb to be not square, but long enough to show what portion of 
the document is on the screen. That way, for example, if almost 
all of the document is on the screen and you're at the beginning 
of the document, you'll see a thumb which occupies almost all of 
the scroll bar, with a small gray area at the bottom. And if you 
click in that small area, you'll see a large thumb move a small 
distance (while the data on the screen is doing exactly the same 
thing), not a small thumb jump grotesquely from the top to the 
bottom of the scroll bar. 

And if I ever get around to having this fun, you can bet ГІ 
do itall without a formally defined control definition, thank you 
very much. 

Does any of this give you the feeling that my favorite 
language is assembly? — the Thought Police 

From: dhands (David Hands, Salem, OR) 

Subject: MPW Print Interfaces 

In the interface files of MPW Pascal there are two files, 
PrintTraps.p and MacPrint.p, that contain roughly the same 
calls. What's the difference and when should one be used over 
the other? 

From: think (Think Technologies, Bedford, MA) 

Subject: Re: MPW Print Interfaces 

PrintTraps.p is the trap-based interface to the Print Manager; 
the traps are implemented in the Mac SE and Mac II ROMs, and 
in System 4.1 or later on all machines. 

MacPrint.p is the glue-based interface, and will work on all 
Macs, on all versions of the System software. 
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From: pmilitch (Peter Militch, Laurel , MD) 

Subject: RESEDIT 

I was experimenting with RESEDIT and using it to look at 
some applications. I found that it will not open the CODE 1 
resource in WORD or MACPROJECT 2. On other applications, 
no problem. I do not get a cannot do message or any indication 
of why it doesn't work - it just doesn't. Any theories on why this 
might happen. 

From: emmayche (Mark Hartman, Fullerton, CA) 

ResEdit won't open resources that are larger than a certain 
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value. What that value is, I don’t know, but it's very obstinate 
about it. (The CODE I resource in Word is probably the heart of 
the program itself, some 300K or more? Why would you want to 
open this anyway? ResEdit is not a disassembler. -Ed] 

From: thecloud (Ken Mcleod, La Habra, CA) 

Subject: Re: INIT/cdev communication 

I'm having a problem with tracking a scroll bar in my cdev's 
DITL. The Control Panel, attempting to be helpful, calls 
TrackControl) BEFORE sending a ‘hitDev’ message, so any 
attempt to use the no parameters, so naturally, aclick in the thumb 
will kill the cdev instantly). I suspect the solution requires 
trickery (perhaps changing the "itemType" of its dialog item?). 
Has anyone else run into this? 

From: Isr (Larry Rosenstein, Cupertino, CA) 

Subject: Re: INIT/cdev communication 

You may need to write a custom CDEF to replace the 
standard scroll bar CDEF. This CDEF can simply call the 
original CDEF for everything except the autoTrack message. It 
is whether you are dealing with a indicator or not. 

From: thecloud (Ken Mcleod, La Habra, CA) 

Subject: Re: INIT/cdev communication 

Writing a custom CDEF within my code might work; it does 
seem like a lot of unnecessary coding, though :-( ‘hierDA’ is an 
example of a cdev that includes a ‘fully functional’ scroll bar in 
its DITL... the standard scroll bar proc is specified in the resource 
file, but perhaps he does some runtime twiddling... hard to Say. 
I'll experiment. I enter a loop which seizes event-handling 
control away from the Control Panel. Each time through the loop, 
I check EventAvail() to see if there's an event (other than a null 
event) needing to be handled; if there's а mouseDown, and it’s in 
the scroll bar's itemrect, I call my DoScroll() function to handle 
it. Allotherevents (including mouseDowns NOT in the scroll bar 
rect) cause the loop to be exited, returning control back to the 
Control Panel...and then back to me, on the next null event. 
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From: dbieber (Douglas Bleber, Alta Loma, CA) 

Subject: PICT display 

HELP!! I am currently using a Mac II w/a Supermac 19" 
color monitor. I am programming under MPW C 2.0.2. I have 
been attempting to convert the PICT file Pascal tech-note ex- 
amples into work-able “C” code. Unfortunately, I have not been 
successful. I would be interested in any “C” source that reads and 
displays a PICT-2 file. Any help would be appreciated. Thanks. 

From: emmayche (Mark Hartman, Fullerton, CA) 

Subject: Re: PICT display 

Here's some Lightspeed C code that I've written which does 
what I think you want to do. This also takes care of picture 
spooling. I'm not sure how much will be applicable to MPW C. 


int  thePath; 

pascal void GetPICTData(dataPtr, byteCount) 
Ptr detaPtr; 
int byteCount; 
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long longCount ; 
longCount = byteCount; 
filErr = FSRead(thePath, &longCount, dataPtr); 


ReadPICTFileCpath, window) 
int path; 
GrafPtr window; 


QDProcsPtr savedProcs; 
CQDProcs myProcs; 
PicHandle myPicture; 
long longCount, myEOF, filePos; 
Rectr; ` 
thePath = path; 
SetStdCProcs(&muProcs); 
myProcs.getPicProc = (Ptr)&GetPICTData; 
savedProcs = window-)grafProcs; 
window->grafProcs = (QDProcsPtr )&myProcs; 
SetPort(window); 
myPicture = (PicHandle)NewHandle(sizeof (P icture)); 
if CfilErrzGetEOFCpath, &myEOF 2) 
return FALSE; 
if CfilErr=SetFPos(path, fsFromStart, 512)) 
return FALSE; 
longCount = sizeof(Picture); 
if (filErr=FSRead(path, &longCount, (Ptr)*myPicture)) 
return FALSE; 
r = (*myPicture)->picFrame; 
DrawPicture(myPicture, &r); 
if CfilErr=GetFPos(path, &filePos)) 
return FALSE; 
KillPictureCmyP icture); 
window->grafProcs = savedProcs; 
if CfilePos != muEOF) 
return FALSE; 
return TRUE; 


Note that there are some casts to QDProcsPtr when you'd 
think it should really be CQDProcsPtr; don't worry about these, 
they work fine and leave the flexibility to return to black-and- 
white should you ever be crazy enough to do so. “filErr” is a 
global error code declared in a .h file. 

Hope this helps - please let me know. [Another good source 
is Dave Wilson's Color Paint Example program in his Macintosh 
II Programming Class Notes, available from the MacTutor Mail 
Order Store. -ED] 

From: andyv (Andrew Voelker, Long Beach, CA) 

Subject: Mac Il bus error 

I wrote a program that works fine on my SE, but it bombs 
with a bus error on a Mac II. What does a bus error mean on a Mac 
II? 

From: emmayche (Mark Hartman, Fullerton, CA) 

Subject: Re: Mac II bus error 

It very much depends upon what you're doing. Generally, 
a bus error means that somebody (generally the CPU) has 
asserted an address and nobody lives there (actually, nobody has 
responded within the time limit of the bus). 

If you can figure out about where you're bombing and post 
some of the code around that point, it would be helpful in the 
diagnosis. 

From: Isr (Larry Rosenstein, Cupertino, CA) 

Subject: Re: Mac II bus error 

You can never get a bus error on the Mac SE (or Plus) 
because of the way the hardware is designed. Your program is 
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still accessing some strange error, but the hardware is mapping 
that access back to some valid memory address. This means you 
could be stomping on random memory locations on the SE. 

From: dbieber (Douglas Bieber, Alta Loma, CA) 

Subject: PICT display again... 

The code that emmayche provided worked great! However, 
I am having two problems: 

1) A color picture created by MacDraw II will not appear 
in color using the aforementioned code. Perhaps further 
‘“‘tweeks” are necessary. 

2) A color picture created by Pixel Paint will appear in 
color. However, the update region (the area of the picture 
window covered by the SFGetFile dialog) is updated in black & 
white. I am using CopyBits in my update function. I have 
retrieved the picture window using GetNewCWindow, and I 
have defined an off screen PixMap for use with the CopyBits 
routine. Unfortunately, when I initialize the system, the pixSize 
variable has a value of zero. I suppose I need to do further 
“initializations” not previously required for B&W. But what?? 

Any code and/or suggestions would be appreciated. The 
February 1988 issue of MacTutor has an excellentarticle entitled 
“Macintosh II: Color Screen Dump FKEY”. The use of Pix Maps 
is demonstrated in a Pascal DA. Unfortunately, no update 
procedures are performed. 

From: emmayche (Mark Hartman, Fullerton, CA) 

Subject: Re: PICT display again 

It is unclear to me how your program is handling the update 
event that it will receive after the SFGetFile dialog clears away. 
If you are updating from an off-screen PixMap, you should be 
sure that the offscreen port is opened with the proper depth, and 
use the OpenCPort command for it. 

I open my palette window first with a GetCWindow call, 
then steal the depth of that window for document windows. 
Works fine unless someone makes the screen shallower on you 
(deeper, we can handle). This is tricky, which is one of the 
reasons Pixel Paint *requires* 256-color mode to be set. (My 
program, Photon Paint, is more intelligent, so it'll operate in 16- 
or 4-color mode. It'll do 2-color mode, too, but that gets boring.) 

If this doesn't give you enough help, let me know and maybe 
we can do something about it off-line. 

From: andyv (Andrew Voelker, Long Beach, CA) 

Subject: my bus error 

I get my bus error on the Mac II in the first instruction of this 
function: 
void DrawCard(thePile, cardNumber ) 


struct pile*thePile; 
char cardNumber ; 


struct cardtheCard; 
theCard = *(thePile-»cards[cardNumber 12; 


the following are global variables: 
struct card ( 
Rectrect 
char suit, value; 
Boolean facingUp; 
) deck (NUM. OF CARDS]; 
struct pile ( 
Rect baseRect; 
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char numInPi le; 

struct Card*cards [MAX_CARDS_IN_PILES ]; 
) playPile(NUM_OF_PLAY_PILES], accumPile[NUM-OF ACCUM.PILES], 
drawPile, discardPile; 


It doesn’t bomb on a Mac SE. 
From: emmayche (Mark Hartman, Fullerton, CA) 
Subject: Re: my bus error 
Try changing: 
theCard = *(thePile->cards[cardNumber]); 
to: 
theCard = *(thePile->cards[(int)cardNumber]); 

I think that the byte-wide subscript may be killing you here. 
It’s probably got some junk in the upper byte(s) which are 
pointing way-the-heck off somewhere. This is a wild guess - 
everything else looks fine. 
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From: sstaton (Steven R. Staton, Dallas, TX) 

From: rustyt (Rusty Tucker, Irvine, CA) 

Subject: File Comments 

I’m trying to devise a way to implement “File commenting” 
ala the Finder.One of my requirements is that the comment is 
accessible even if the Finder is running and has control of the 
Desktop file, it is not necessary (although desirable) that the 
Finder display this comment in it’s “Get Info” Dialog. 

An approach that I’m currently considering is to create a 
“ЕСМТ” resource and add it to the file's resource fork ( both 
APPL and doc ). One of the benefits of this strategy is that the 
comment would be passed along when the file was copied or 
transferred via Modem. 

My questions are: 

Will this crash any of the existing Applications out there? 

Will the Finder recognize this RSRC when it updates the 
Desktop file?Is this completely immoral? 


From: alex (Alex Curylo, Ottawa, ON) 

Subject: Re: File Comments 

I think I've heard that messing around with an application's 
resource file just isn't a cool sort of thing to do. 

F'rinstance, any application that's had 'JumpStart' move its 
resource map to the beginning of the resource fork will go belly 
upafter you do this FCMT thing with it. Anybody in general who 
expects their resource map not to change will be in trouble. 1 
don't know any specific applications that brain-dead, but I'm 
sure you'll find them for us. 


From: rustyt (Rusty Tucker, Irvine, CA) 

Subject: Re File Comments 

Alex, I was thinking about your comment about "Jump 
Started" App's crashing after having their RSRC fork modified. 
My original reaction was very similar. Somehow it just doesn't 
seem Kosher to modify a file that you don't “own”. 

But isn't that what a large number of people do with ResEdit 
etc. ? Modify resource forks to customize an application? Isn't 
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that part of the greater purpose of the Resource Manager? 

As a little background, the FCMT resource is the STR 
resource type used by the Finder to manage the info string in the 
get info comment. It looks as if it takes the File number created 
by the File system and uses it as the res ID #. I'll test that this week 
and let you know. 

Anyway I got to thinking about the other resources modified 
by the Finder and started poking around in my Desktop file for 
a SIZE resource that would correspond to one I modified in an 
APPL through the “Get Info” dialog. No SIZE RSRC’s in the 
desktop file. Hmm, I looked in my APPL file and found a SIZE 
RSRC=0 put there by the Finder. 

Maybe somebody from Apple could tell us if the SIZE 
resource is a special case, or if it's OK to add resources to files not 
owned by that Application. 


From: rdclark (Richard Clark, Tustin, CA) 

Subject: HyperCard errors 

I may be proven wrong, but the only mention I’ ve ever seen 
of the errors is in Goodman’s Developer’s Guide, and he waves 
them off with the comment “one of HyperCard’s many internal 
consistency checks failed” and proceeds to note that your stack 
is now damaged beyond repair. No explanations. No hope of 
recovery. (almost makes one want to take up knitting instead.) 


From: jfischer (Jeff Fischer, Carbon Canyon, CA) 

Subject: Hypercard errors 

Yeah, I’ve got that book. Big help, right? Why couldn’t he 
have supplied them in an appendix with some sortof “at your own 
risk" caveat? Geez, I’ve gota 4.5 MEGABYTE stack that I' d do 
anything to recover, if only I could figure out what error 5544 is 
trying to tell me! Is the structure of a stack published? I mean, 
howit'salllinkedtogether internally? Ihave aPD program called 
"Stack Detective" that lists all the parts and how much room they 
occupy, I wonder where he got his info? Oh, well...I'll stop 
rambling—anyone out there with the low-down on the Hyper- 
Card error meanings and/or stack structure documentation 
PLEASE come forward! 


From: ms (Mike Steiner, Sierra Vista, AZ) 

Subject: Re: Hypercard errors 

With that large a stack, this might not be workable, but... If 
you change the file type to TEXT, you can then read the entire 
document with a word processor. All the scripts and the text that 
appear in fields (but not graphics text) will be recoverable. I think 
that object names will be identified, but that probably won't be 
of much help though. 


From: jfischer (Jeff Fischer, Carbon Canyon, CA) 

Subject: Re: Hypercard errors 

Thanks, Mike. You're right, this stack is too large for that 
solution. It is built largely of imported text, and I can rebuild it 
that way (since I saved the source), but I was trying for an even 
easier way out. I’ ve been through the stack pretty thoroughly with 
FEdit, and discovered some pretty interesting things, but 
couldn't quite get enough of a handle on it to completely recover 
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it. 

I now have in my possession Apple's tech notes on Hyper- 
Card (all 3!). The one titled “HyperCard File Format" says 
"HyperCard's file format is proprietary and will not be docu- 
mented." Sigh. Oh, well, back to the quest! 


From: ms (Mike Steiner, Sierra Vista, AZ) 

Subject: Re: Hypercard errors 

Well, Jeff, maybe as a side effect of your problems, you 
could put together those pretty interesting things you discovered 
about HC and publish an article in MacTutor (at least you would 
get a few $$ for your troubles). 


From: jfischer (Jeff Fischer, Carbon Canyon, CA) 

Subject: Re: Hypercard errors 

Hmmm. Now there's an idea. Maybe I'll try to wake up the 
guy that wrote Stack Detective (he hasn't cashed my shareware 
check in two months—a bad sign). Now THERE’s a guy who 
knows the guts of HC. I wonder where he got his info? 


From: alex (Alex Curylo, Ottawa, ON) 

Subject: DeskHook 

Has anyone out there ever used the global ‘DeskHook’? 

It looks like you could do some neat things with it, but the 
Multifinder programming docs say it's not supported anymore. 
Comments, anyone? 


From: chally (Mark Chally, West Covina, CA) 

Subject: DeskHook 

Yeah...Iused to use it—until I was told it would break..it was 
great. Using it, you could send the address of a routine that polls 
the serial port and sends checksums in response, etc...just as long 
as it doesn't draw on the screen or change the menu items. There 
was also a dialogHook. I use neither anymore because I'm told 
they'll break. I will instead attempt to do a VBL task to do what 
I need to do 100% of the time instead of “patching it in" as I’ve 
described. 


From: ericlim (Eric Lim, Flushing, NY) 
Subject: MPW Resume Function 
MPW Users: 
Add the following lines around your DirectoryMenu and 
BuildMenu code in the UserStartup file: 
$2 $9 82 5S SUES 8 OF 8S £5 8S 58 oe Se oS ok oe n ii HH E HO HO OL 8 Os £8 8 Os 8 HUH oe Os os as UE GN 4 
if ‘exists -f “(Shel 1Directory}MPW.SuspendState” ’ 
ее (ShellDirectory)Resume"' 
else 
8 place your regular DirectoryMenu and 
8 BuildMenu code here 
DirectoryMenu ‘(Files -d -i "(MPW)^"Exemples" 6 
|| Set Status Ø) З Dev:Null’ ‘Directory’ 
BuildMenu 
end 
$3 $0 53 $5 SES £8 OS 28 ES £8 o£ HH HH HH HH HH HH HH HH HU HUU E AG 6 
NOTE: Substitute the “^^ with Option-X. 
Append the following line to the Quit file: 
НЕННННННИНННННННННЕННЯННЕННИННННННННВННННННННННННННН 
“(Shel 1Directory) “suspend 
ЯНАНЕНННННННННННИНННННННИНННННННННННННННННННННННННЯН 
Now you have a real ‘Resume’ function not only when you 
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launch an application, but also when you ‘Quit’ from MPW. If 
you want to start with a clean desktop, just trash the 
MPW.SuspendState file and launch MPW Shell. Enjoy! 


From: kdc (Kevin Connery, Bellflower, CA) 

Subject: Novice questions re: C 

I realize this is probably pretty basic for most of you, but 
everywhere else I asked it was too advanced, so please bear with 
me. 

I’m just starting to program on the Mac, have decided that C 
is the language to use [don’t ask me why!], and have discovered 
a number of obstacles in the path of smooth coding.... 

Are there any good books available on using the toolbox 
with C? I’d prefer arecommendation from someone who’s using 
one, but barring that, ANY titles/authors would be appreciated. 

And recommendations as to development systems also. I’ ve 
heard good things about LSC, MPW, and AztecC, and have a 
fairly limited C background, with even more limited Mac coding 
background [none]. Suggestions? My goal is NOT to make the 
next PageMaker-level application, but I want to be able to 
effectively use the power the machine is capable of. Current 
system is a 1 meg Mac II, so anything which works here is 
possible...Many thanks in advance! 


From: thecioud (Ken Mcleod, La Habra, CA) 

Subject: Re: Novice questions re: C 

Kevin, you can't go wrong with LSC... less than $100 mail- 
order, and worth every penny. Since you're “not going to be 
making the next PageMaker," you can probably even use the 
source-level debugger on your 1 meg machine! (There's a trick 
to it, but it's not difficult) Even without the source- level 
debugger, LSC is far and away the best C environment for the 
novice programmer (in much the same way that Lightspeed 
Pascal used to be the best Pascal environment). As for books on 
using the Mac toolbox with C, get your hands on “Using the 
Macintosh Toolbox with C" by Huxham, Burnard, and 
Takatsuka; published by Sybex. The original edition used ‘Mac 
C’ in examples, but I've heard there's an updated version in 
which all the examples are now in LightspeedC. Better yet, 
downloadall the sample C source code you can, and play with it... 
‘c’ how it works. Good luck. [Buy the back issues of MacTutor, 
published in our yearly Complete MacTutor books. -Ed] 


From: tycho (Donald Tycholis, Westminster, CA) 

Subject: Re: Novice questions re: C 

I have been using C on the Mac for the last 4 years, and am 
still somewhat of a novice with respect to the Mac Toolbox. I 
have used Manx Aztec C (currently with the new source level 
debugger) for 4 years, MPW C for 2 years, and LCS 3.0 for about 
2 months. LSC is the winner for ease of use, speed of compilation/ 
link time, and ease of debugging. In short, it is the most 
productive tool for me. Of course I had to upgrade to 2 MB and 
MultiFinder to run the debugger, but I have made more progress 
on my “project” in the last two months that I have had LSC 3.0 
than I did in the last two years using Manx and MPW. Of course, 
both of the other compilers have their strengths; they are better 
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suited to larger, professional programming projects (especially 
MPW). I just program on the weekends and on an occasional 
holiday while the family is downstairs chatting around the turkey 
in the oven so I probably qualify as a bonafide amateur Ma- 
cHacker. LSC is the best as far as I’m concerned, and for the first 
time the Mac has a C compiler which is better than MicroSoft C 
5.0 on the PC (which I use at work)! (Actually, MPW and SADE 
may be better in some ways. ГІ never know because I cannot 
justify buying a MAC IIx + 4 MB RAM just to get the same 
capabilities that LSC 3.0 provides). The latest rumor is that LSC 
will support Object C soon and C++ later, so I am content 
with LBC at present. 

As far as toolbox programming, I recommend “Using the 
Macintosh TOOLBOX with C” by Takatsuka, Huxham, Burnard 
( Sybex). For getting an understanding of The Mac internal 
concepts and debugging, I highly recommend both of Scott 
Knaster’s books (How to Write Macintosh Software is the first 
and I don’t remember the second since I just browsed it at B 
Dalton’s). 
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From: Rguerra 

Re: FINDER QUESTION 

Does anyone have any idea as to how the Finder places icons 
in its windows? I know about the FinderInfo fields returned by 
the PBGetCatInfo call, but what coordinate system is being used? 
The Finder does a SetOrigin on each of its windows so the 
coordinate system is somewhat odd. The POINT coordinates in 
the FInfo record very often will NOT correspond to a point in the 
visible window even though Ican see the icon. Also, does anyone 
have any information on how the Finder keeps track of the files 
in each of the windows and how it determines which icons are 
selected and are to be opened by a double-click or an “Open” 
menu. I know this is all undocumented but Га very much like to 
know how this works. Thanks! 


From: Spud 

Re: MultiFinder bug??? 

I have noticed that when calling an alert in the background 
under MultiFinder, the alert does not re-draw correctly. I have 
noticed this in many commercial apps, as well as my own. Here's 
the sequence of events: 

1) Write an app that waits 5 seconds, and then puts up an 
alert. ProtoTyper, no problem. 

2) Run the app. Within those 5 seconds, switch into another 
application whose window covers all others. 

3) Okay, 5 seconds are up, so switch back into your original 
program. Notice that the icon and the alert's bold item are not 
drawn. 

Is this a bug in MultiFinder, or am I just seeing things? If it 
is a bug, then how can I program around such a dilemma? 

Thanx in advance, 

-Spud 
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From: Rdclark 

Re: MultiFinder bug??? 

Spud, 

Basically, background applications shouldn't be putting up 
alerts — that is the privilege of the foreground application. You 
should use the Notification Manager instead, (which can put up 
analert in frontof the frontmost application if you really have to.) 

The Dialog Manager assumes (correctly) that modal dialogs 
(and alerts) will always be the frontmost window, and so have no 
redrawing code. 

... Richard 


From: Rguerra 

Re: Dialog Redrawing 

Ah, but that doesn't mean that modal dialogs shouldn't have 
redrawing code! What about the case when a modal dialog is in 
front and a screensaver kicks in? If you don't handle the update 
event, the user is left with a blank dialog except for whatever 
buttons, etc. that were part of the DITL item list. If you need to 
draw frames, outline buttons, etc. you can either add a UserItem 
to the DITL (a custom drawing routine) or handle updates in a 
dialog filter proc that you pass to ModalDialog. I agree about 
using the Notification Manager from the background. You might 
want to make sure your program is MultiFinder-A ware and keep 
track of whether you're in the foreground or background and call 
your normal dialog in the foreground and the Notification 
Manager dialog in the background or else do nothing until the 
user brings you to the foreground again. 

Rich 


From: Rdclark 

Re: Dialog Redrawing 

Ah, but that doesn't mean that modal dialogs shouldn't have 
redrawing code! I agree — but who's going to write the ROM 
patches to do it «grin»? Really, you have to assume that a modal 
dialog will be responded to immediately, and that your screen 
saver probably won't have the chance to kick in. (By the way, 
thereis limited redrawing code for alerts, since your button's 
contents and any static text will be redrawn...just not the icon or 
the outline around the button.) 

...Richard 


From: Mark Worthington, Worcester, MA 

Subject: XCMD intercepting mouseUp 

I have written an XCMD which is called within a 
mouseDown handler in a HyperCard script, which tracks the 
mouse until it is released. No problem. Recently I decided to 
allow the user of the XCMD to be able to specify a parameter by 
which he could choose to have the XCMD intercept the inevi- 
table subsequent mouseUp event, or let nature take its course and 
have HyperCard receive the event and do with it whatever it was 
supposed to. I therefore puta GetNextEvent loopat the end of my 
XCMD, expecting this would intercept one mouseUp event and 
then exit the XCMD. But it doesn’t intercept the mouseUp at all. 
I have added several diagnostic lines of code and found that the 
loop really is not finding a mouseup. I gave the loop 10 seconds 
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to receive such an event. I also put a mouseUp handler in the 


_ button to beep 5 times. Lo and behold, when the 10 seconds had 


elapsed, the button beeped 5 times, and my diagnotics reported 
no mouseUp was detected by the XCMD. Now I know Hyper- 
Card 1.2.2 is supposed to change HyperCard's habit of sending 
itself a mouseUp message *before* removing the mouseUp 
event from the queue (oh, yes. I am using HC 1.2.1), but that 
doesn't seem to be the problem. What is HyperCard doing to me, 
and how? Would using WaitNextEvent make any difference, 
and if so, why? Please help. Thanks so much. 


From: thecloud (Ken Mcleod, La Habra, CA) 

Subject: trouble intercepting mouseUp 

You might try setting the system event mask to enable 
mouseUp events yourself (using SetEventMask()...see the Tool- 
box Event & OS Event chapters of IM), since it sounds like 
HyperCard is disabling mouseUp events before calling your 
XCMD. Alternatively, you might want to try calling 
GetOSEvent() instead of GetNextEvent(), since the system сап 
intercept events gotten with GetNextEvent() before your code 
ever sees them. 

Somebody more familiar with HyperCard should be able to 
give you a better answer (or else an ‘official’ one); in the 
meantime, hope this proves helpful. 


From: macww (Mark Worthington, ) 

Subject: trouble intercepting mouseUp 

Ken, Thanks for the reply. I'll try your ideas. In the 
meantime, if anybody else has more specific knowledge of what 
HyperCard is doing, or where else I might find out, I would 
appreciate it. Even if one of Ken's suggestions works, itis always 
unsatisfying to “fix” something without understanding what got 
“fixed.” Thanks again, Ken. 


Volume 5, Number 7 


From: Rguerra 

Re: cdev “shell” 

It occurs to me that writing and debugging cdev’s would be 
greatly simplified if the programmer could simply place the cdev 
unit into a supporting shell program that would emulate the 
function of the control panel. This shell would send the appro- 
priate cdev messages to the user’s cdev unit. The programmer 
using LSC, LSP, or even SADE could step through the instruc- 
tions of the cdev as per usual with an application. Has anyone 
ever seen such a beast? If so, would you be willing to share it with 
the rest of us? If one doesn'texist yet, what would go into writing 
one? Any comments? Rich 

From: Ctli 

Re: Res Error Proc (Fw by Sysop) 

Anybody know how to redirect ResErrProc to a light speed 
pascal routine? The following code does not work. 


ResErrProc = ^ longint; 
ResErrProc = pointer($0aF2) ResErrProc^ = Ord4(@MyErrorProc); 
Procedure MyErrorProc ; 
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begin 
Code := 3 ; 


end; (bu the wau Code is a global variable) 


From: Politik 

Re: AppParmHandle 

Have you ever played with the Finder Info Record, a handle 
to which is found in AppParmHandle($AEC)? I’m trying to 
change the record between application launches. Here's what 
I’m doing: 


AppParmHandle = $АЕС; 
FinfoRec = record 

mymez: Integer; 

mycount: Integer; 

volref: Integer; 

mytype: LongInt; 

versnum: Byte; 

notused: Byte; 

namelen: Byte; 

myname: string[30]; 
end; 
FInfoRecPtr = ^FInfoRec; 
FInfoRecHndl = “FInfoRecPtr; 
myParms := HendleCAppParmHandle?; 
( $AEC - low mem glob ) 
HLockCHendleCnyPerms 2); 
myF := FInfoRecHndlCnyParms?; 
myF^^.mymez := 9; 
myF**.mycount := 1; 
myF**.myname := ‘Jean’; 
etc.... 
HUnLockCHandle(myParms 2); 


I can see everything changing in Lightsbug, but for some 
reason it crashes after the volref is changed Any ideas? Help 
appreciated... 

From: Ctli 

Re: ResErrProc 

Redirection of the ResErrProc pointer needs to be a longint 
instead of just an integer. Also, in Lightspeed Pascal, any file 
function such as Reset,Rewrite or write doesn't seem to behave 
nicely. If the disk is locked, there is no invalid return, rather you 
are dumped out to the system with a id=08. 


From: Nicks 

Re: My Cdev is a little confused. 

I'm writing a cdev in LightSpeed C, and having a weird 
problem. If I try to change the state of the Pen with a PenPat or 
PenNormal call, the pen pattern gets set to garbage. A short 
sample might be: 


PenPat(grey); 
FrameRect (&anyRect ); 


- This will fill the specified rectangle w/ garbage. I assume 
that the problem has to do w/ the fact that I’m running this code 
inside a DA, and I can’t get to the QuickDraw globals? Or am I 
on the wrong track completely? Thanks in advance. 

From: Batista 

Re: My Cdev is a little confused. 

The problem is that you are trying to use a QuickDraw global 
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when in fact you don’t have it. When Think C runs it allocates 
these globals for QuickDraw and you initialize them when you do 
the InitGraf(&thePort); in a cdev there is no such a thing, 
therefore when you do the PenPat(& gray) you are dereferencing 
who knows what. What you have to do is make up your own 
pattern. 


Pattern myGray; 
myGray(@] = myGray[2] = myGrayl4] = muGrau[6] 


= = 170; 
myGray[ 1] = myGray[3] = myGrag(5] = myGray[7] 


85; 


Then do a PenPat(myGray); and you'll get the result you 
want. Ricardo 

From: Nicks 

Re: My Cdev Is a little confused. 

Thanks for the info. I assumed thatit had to be something like 
that. Questions: Does this affect other things besides PenPat? Is 
there a way to “find” the QD Globals that the Control Panel is 
using and address those? Where in IM is all this addressed? 
Thanks again. 

From: Rdclark 

Re: My Cdev is a little confused. 

A better way to fix the “bad patterns" problem is to set up AS 
at the start of your code and restore it when you're done. If you 
do this, А5 will point to the start of the current Application’s 
globals, and the end of the current QD globals — which is exactly 
where it should be when you need to use QD. ...Richard 

From: Nicks 

Re: My Cdev is a little confused. 

Yeah, that's what I was assuming. BUT: I'm a bit new a this 
"where's my globals” stuff. How do I get the right value of a5? 
Get it from CurrentAS, then use in-line assembly (which I have 
no clue how to write)? Or can I use SetupA5 & RestoreA5? IM 
says these are for interrupt handlers only. Do they have other 
uses? BTW: my work-around for the original problem was to just 
use a PICT resource with a grey pattern in it, the use CopyBits to 
blast that into whatever rectangle or whatever I needed to use it 
in. Ugly, huh? 

From: Noisy 

Re: MacPaint II diagnostics 

Having recently attacked MacPaint II with MacNosy (the 
ONLY programmer's tool), I kept encountering DIAGS every- 
where. A rainy Monday evening with the wife at work gave me 
the time to track it down: it seems that Claris neglected to remove 
about 4K of diagnostic code, basically because it is thoroughly 
embedded everywhere. It doesn't seem to do much, apart from 
double-check various drawing actions, but it *can* be enabled by 
patching the application: Using any decent File-Mangler (I used 
FEdit+) do the following: Replace: 6CE6422D E59349ED with 
6CE61B40 E59349ED There should be only one occurrence, and 
never patch your original, blah, blah. Cheers! Noisy 

From: Rguerra 

Re: MacTutor Index (Fw by Sysop) 

Is there an index for the fourth volume of the collected 
articles of MacTutor. I’ve got all the original issues but I'd like 
an index. How about posting one here, or even publishing an 
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Index to a volume in the first issue of the succeeding volume? 

[MacTutor now sells an index a text with tab fromatting for 
adding into your favorite database application. It is a nominal 
fee ($2 plus s/h) especially since all the work I've put in to 
prepare it initially.-KC] 

From: Dale 

Re: A sick MPW text file?? 

I'm not sure what category this falls into, but here goes: I’ve 
just run into the strangest problem with MPW 3.0. It seems that 
editing the file SANEMacs881.a in the MPW Shell and then 
trying to Revert the file explicitly causes the Shell to hang. This 
happens with any copy of the file that's simply a Finder copy or 
an MPW Duplicate of the original, but there's a bizarre way to 
create a healthy copy: first create an exact copy of the SANE- 
Macs file, then open it and Catenate the text of the original file 
into the open window. If you save that the Shell will behave 
normally when you edit it. Interestingly enough, if you simply 
create the copy with Catenate instead of first copying the entire 
file, Compare reports that the two files don't match anywhere! 
Very strange, since (as far as I know) Catenate simply transfers 
the data fork and Compare just compares the data forks. What's 
even stranger, using Catenate without opening the file first 
doesn't work: your copy will hang the Shell as before! Do any 
of the experts out there have a clue as to what's going on here? 

From: Macrobin 

Re: MacTutor Listings Font 

This is a preety simple question. What is the Font used for 
Program Listings in MacTutor. I have been looking for a nice 
clean sans serif, monospaced Font for a while. MacTutor pro- 
gram Listing appears to be just what I want. What is it and where 
can I get it. Thanks. 

[MacTutor uses a special LaserWriter version of Monoco 
call Thin Saratoga that was created especially for program 
listings by Michael Mace, now at Apple Computer. We might let 
you have it if you promise not to distribute it to our competition! 
-Ed] 
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From: Caro 

Subject: mac logic board 

I have a problem with my Mac+ logic board (I already 
KNOW it's not RAM or any peripheral) 

--оп power-up it puts up a black screen and sad Мас 

—doesn’t even get as far as the RAM test 

—and posts an error code of 030020. 

Apple doesn’t support chip level repair, and I really don’t 
want to pay 350 plus trade in for what is probably a 2.00 chip. 
Any Mac hardware hackers out there? I’m a programmer and my 
boss is equally expert with hardware and software. Anyone know 
what this error message means? Other handy hints? Where to get 
a complete schematic? 


From: Smugwimp 
Subject: mac logic board 
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The chances are it is one of your ROM chips. You should 
have snap in chips as far as the ROM goes. Call “Pre-Owned 
Electronics” (sorry I don’t have #). They have ads in the 
“Computer Shopper" and sell them for around $125 a set. If you 
do change them yourself 

a) Be certain you are out of warranty 

b) is Applecare not an answer ? 

c) if you DO IT, be SURE to observe anti-Static procedures 
SO as not to blow the rest of your Mac replacing one section. — 
> SmugWimp 


From: Shunt 

Subject: Xcmds and code greater than 32K 

HELP!! 

I’m in the process of writing a series of XCMDs for Hyper- 
Card; having got right through to the 49th - now I’ ve have run into 
problems. 

The code for this particular command is too large for a 
standard 32767 byte segment and, on linking, I have a stream of 
error 48 messages whereby the PC-relative edit offset is out of 
range (jump table calls greater than 32k away). I have tried 
reorganizing the procedures, functions and include files- unfor- 
tunately I cannot strip out any more of the code. I can set the 
segment size to accommodate the code OK, and have tried -srt 
option on linking and -b option on compiling: All to no avail. 

Any suggestions please! These Xcmds will also be dupli- 
cated as 4D Externals so any Help on this front would also be 
greatly appreciated. 

Many thanks Doug Hunter. 


From: Craigk 

Subject: Xcmds and code greater than 32K 

I had a similar problem programming the Manhattan ZIP 
Code Locator. In trying to handle over 800 streets and thousands 
of addresses, I just resorted to 3 XCMDS. If what I wanted didn't 
get done in the first one, I just called the next one. I realize that 
this is not a direct answer to your question, but that is how I 
worked around the 32K limit. 


From: Spud 

Subject: XCMDs with CODE? 

I was about to write an XCMD that calls an external CODE 
resource, when someone informed me that HyperCard can’t do 
that!!! Is it true?!? 


From: Rguerra 

Subject: KeyCode Question 

I need to translate a keyCode (obtained from the Even- 
tRecord message field using the KeyCodemask and BitAnd) 
BACK into an ASCII character. I can't just get it from the Event 
message because modifier keys will give you strange characters 
and I just want exactly what's on the key that was pressed. I tried 
using KeyTrans but I can't seem to make it work. Can anyone 
help me with this!?!? I'm up against a deadline and I need to get 
this problem solved. Thanks! 

Rich 
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From: Wenbrown 

Subject: List Manager Follies 

Does anyone out there use List Manager?? I have been 
struggling to write a simple two-dimensional list for data display 
and entry. I have succeeded in using Lnew to create a list and 
attach it to a window. I have used Lsize to adjust the size of the 
list when the window is resized, and several other standard tricks. 
Here’s the problem: When the mouse is clicked inside the 
content region, my program crashes with an “Address error.” 
The offending statement is: 


TempBoolean:= Lclick (NewPoint, event.modifiers, ListHand) 
Amazingly, this statement works fine when the mouse is 


clicked inside the scroll bar! The list scrolls beautifully. But 
when it’s clicked inside the displayed list itself, the Address Error 
occurs. I have checked the values of NewPoint.v, NewPoint.h, 
event.modifiers and ListHand (the handle to my list), and all 
values are reasonable! My program is translated from a 
Lightspeed C program which appeared in MacTutor in March 
1989: “How to Write a Spreadsheet in LS C.” 


From: Skaros 

Subject: VBL inits 

I’ ve been trying to install a VBL at init time but have not been 
successful so far. My strategy has been to compile a simple 
VBL(something that posts an APP1 event) as a ‘CODE’ re- 
source. Then my installer sets up a test window and installs the 
VBL in the following way: 1)get the resource,2)lock the handle, 
3)get its size, 4)allocate a block of memory with a ‘newptr’ call, 
5)do a *blockmove' of the dereferenced locked handle of the 
‘CODE’ resource into the newly allocated block of memory. Of 
course, newptr gives me a block in the application heap, but this 
is just a pilot program. I could easily define a ‘newsysptr’ call 
with inline code to get me a block in the system heap. Anyway, 
my VBLinstalls, interrupts once and then nothing. When I quit 
my installer, I get a ‘qerr’ this means my VBL isn’t in the 
queue. My guess as to what is happening is that my vbl counter 
that is supposed to be initialized during every cycle of the VBL 
task with the statement—vbl rec.vblCount :=10; really isn't 
working. After all , how cana VBL task that is moved into a heap 
with *blockmove' ever know where its VBL record is. 
Therefore,it doesn't reset its counter and therefore it expires after 
one interrupt. How do I pass the address of the VBL record used 
in the installer program to the VBL task so that after the VBL is 
installed, it resets its counter?Or, is there another way to set up a 
VBL task as an init? 

Stefan Karos 


From: Rdclark 

Subject: Window Mgt, THINK Pascal 2.01? 

There are several common problems you can have when 
resizing a window. The First, the 4 lines you'll need should look 
like this: 

SetRect(sizeLimits, 32, 32, screenBits.bound.right, 

screenBi ts .bounds bottom); 


result := GrowWindow(whichWindow, theEvent.where, sizeLim- 
its); 
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if (result © 0) then 
SizeWindowC(whichWindow, LoWord(result), HiWord(result), 
TRUE); 
Now, for the problem areas: 1) your “sizeLimits” rect is 


undefined, or has a minimum size (the first 2 numbers) of (0,0). 
2) TheEvent.where is given to you in GLOBAL coordinates, 
which GrowWindow also expects. Are you calling “Global- 
ToLocal”, perchance? (If so — don’t!) 3) LoWord() and 
HiWord( could be reversed. 4) You're not checking to see if the 
result is non-zero (0 = “no change!) before calling SizeWindow. 
5) The window's defProc is set to be a NoGrowDocProc (which 
sounds like something you'd order at a Chinese restaurant) 
instead of the more common “DocumentProc”. 

Enough of a hint? 

...Richard Clark 

Apple Developer University 


From: Wenbrown 

Subject: List Manager Scrolling 

I am looking for a “hook” that will enable my program to 
respond to scrolling of a two-dimensional List, so I can rewrite 
some column and row headings on the screen *as the list is 
scrolling*. List Manager'sL CLICK function has a hook, stored 
in the LClikLoop field of the list, that the programmer can point 
toacustom routine. Inside Macintosh IV says that the routine will 
be called while the mouse is clicked or held down in the list 
rectangle or the scroll bars, but it does NOT work properly in the 
scroll bars. The programmer's custom routine only gets called 
when the mouse is clicked in the list's visible rectangle, not the 
scroll bars. 

This problem is discussed in the article “How to Write a 
Spreadsheet" in the March 1989 issue of Mac Tutor. The author 
says this problem can be fixed by installing a pointer (to your 
custom routine) in the system global variable DragHook ($9F6). 
Well, I finally succeeded in installing the pointer, but it only 
works in the wrong situations: My routine is called while the 
scroll bar's "thumb" is being clicked or dragged, but it is *not* 
called while the mouse is held down in the scroll bar's “arrows.” 
Thus, I have the same old problem: I can't update my row and 
column headings until the mouse is released. This looks tacky 
and confusing to the user. Is there some other approach to solve 
this problem, or do I have to give up on List Manager and display 
all my data using QuickDraw? 


From: Ivano 

Subject: Help Compiler using Pascal 

I am trying to use Robert Monsen Us Help Compiler in a 
MPW Pascal program. The calling procedure written in TCU is 


as follows: 
Coo 


Handle rsrcH; 
ProcPtr pp; 
" (rsrcH = GetResourceCCODE, 2000)) 


HLock(rsrcH); 

рр = (ProcPtr) *rsrcH; 
(*pp)(); 
ReleaseResource(rsrcH); 
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) 


In rewriting this to pascal, I am having trouble with the 
(*pp)O. If my limited C experience is correct, what I need to do 
is go to the address of CODE 2000 pointed to by pp. Pascal 
isn'tto friendly with ProcPtr's, any suggestions would be appre- 
ciated. 

Ivan L. Ossander 


From: Gurglekat 
Subject: Help Compiler using Pascal 
Here's what I use to jump to the external transfer protocol 


code resources in my terminal program: 
procedure LaunchProto (transType: resType); 
var 
protoName: Str255; 
theProto: Handle; 
theProtoID: integer; 


procedure CallProto (seriallnput, serialOutput: integer; 
itsID: integer; macBinary: boolean; p: Ptr); 
inline 
$205F, $4E90; 


begin 
GetItemCGetMHandleCtheMenu), theItem, protoName); 
theProto := GetNamedResource(transType, protoName); 
if theProto = nil then 
Message(noProtocol, cautionIcon) 
else begin 
GetResInfoCtheProto, theProtoID, transType, protoName); 
HLock( theProto); 
CallProtoCserialInput, serial0utput, theProtoID, true, 
theProto*); 
HUnlockCtheProto?; 
HPurge( theProto); 
end; 
end; 


I'd show you the original note from THINK I got on 
CompuServe, but CIS might take offense. 


From: Bryce 
Subject: Setting current folder 
Iam using afilter from SFPPutFile to allow the user to create 
anew folder. Does anyone know how to enter the created folder 
from within the filter? The code I' m using is: 
function MyPutFileDlg Citem: INTEGER; theDialog: 
DialogPtr) : INTEGER; 
( This filter is used to allow the user to create a new folder 
from within SFPPutFile ) 
const 
CurDirStore = $398; 
var 
topLeft : Point; 
curDirPtr : ^Longint; 
dirParmBlk : HParmBlkPtr; 
begin 
case item of 
-IntOne,getOpen : begin 
firstCall := true; 
MyPutFileDlg := item; 
end; 
newFoldButton : begin ( RNew FolderS button pressed ) 
topLeft.h := 90; ( top left horiz coord for 
Put File dialog ) 


topLeft.v := 75; ( top left vert и "и r 


€ The Best of MacTutor, Vol. 5 


“ «c hit any key D^ ) 
firstCall := true; 
; SFPPutF ileCtopLeft, Enter New Folder 
пате: ^, ‘Empty Folder’, NIL,Reply,NewFoldID, @MyFilter); 
firstCall := true; 
if Reply.good then begin ( Create the desig- 
nated folder } 
curDirPtr := Pointer(CurDirStore); 
putFileVRefNum := Reply.vRefNum; 
with dirParmBlk* do begin 
ioCompletion := NIL; 
ioNamePtr := @Reply.fName; 
ioVRefNum := putFileVRefNum; 
ioDirID := curDirPtr^; 
end; 
theErr := PBDirCreateCdirParmBlk,false); 
MyPutFileDlg := 101; ( Tell SFPPutFile to 
update file list ) 
end; 
end; 
otherwise 
MyPutFileDlg := item; ( Pass control back to 
SFPPutFile ) 


end; ( cese ) | 
I’ve seen this done in Raymond Lau’s SFVol init. Bryce 


From: Nicks 

Subject: WMgrPort ?’s 

How do DA’s such as BackDrop update the whole screen? 
I wanted to try the Disk icon INIT from the May MacTutor in real 
time, changing the icon, then informing the Mac that the screen 
was invalid. I tried getting the WMgrPort (yeah, I know this is a 
no-no, but I' m just spelunking for fun, not publishing), setting the 
port to what was returned, getting the portRect, then calling 
InvalRect with it. Boom! Same thing happens when I get the 
GrayRgn and call InvalRgn. 

Sample: 


GrafPtr oldport, wport; 
Rect r; 
GetPortC&oldport); 
GetWMgrPortC&wpor t); 

SetPort(wport); 
r = wport->portRect; 
InvalRect(&r ); 
SetPortColdport) 


The code appears to blow up in the InvalRect call in the 
ROM in EqualRgn with a odd address. Am I missing something 
stupid, or is there another approach to doing this? Thanks in 
advance. 


From: Batista 

Subject: My Cdev is a little confused. 

The Control panel may not be using globals, but, if itis, then 
itis using them of A4. Thatof course is of no help and you should 
not even try to use anything that belongs to the control panel. If 
they happen to have some globals addressed of A4 you don'teven 
know what they are. The problem you had with the pattern would 
apply to anything that is one of the “QuickDraw Globals" in an 
application such as color and patterns. The easiest way to get 
around this things is to make your own variables when you need 
them. The AppleTalk project of LSC makes a socket listener to 
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get requests, and it is inside the code, so don’t try doing things 
with AppleTalk in resource that may get moved like cdev’s. 
Ricardo Batista 


From: Macww 

Subject: My Cdev is a little confused. 

Make sure you take a look at both Tech Notes 180 and 208 
if you hope to do SetupA5Q and КеѕіогеА 50) in a MultiFinder 
environment. I think they both used to be on Mousehole 
Download. I am just now trying to get used to this new BBS host 
software, so I haven’t check the files section to see if those tech 
notes are posted. If not, leave a note requesting them. 


From: Pkram 

Subject: file busy 

I have adapted the text editor in “Using the Macintosh 
Toolbox with C” for Aztec C 3.6b. However whenever I save a 
document created by this editor, other applications such as Word 
3.01 or Edit, cannot open the document without getting an alert 
stating that the file is busy and can only be opened with read only 
permission. Ithen used MacTools and checked the busy flag. The 
file according to the busy flag, was NOT busy. Where in IM can 
I find the answer to this problem? 


From: Fischer 

Subject: Editing in a scroll back buffer 

I am currently developing a DA with X/Y Modem file 
transfer, Hayes compatible modem control, and Scroll Back 
Buffer, in MPW C. I have reached the point where I have to 
implement a text selection (Copy, Cut, Paste ...) in my Scroll 
Back Buffer. I haven't found any concrete idea on how to do this 
in MacTutor. I feel frustrated because I have to 'reinventer la 
roue' for this. Is there anybody here who could help me ? Thank 
you. Pierre. 


From: Mike 

Subject: C-ing is not believing! 

I have recompiled some XFCN’s written in LightSpeed C 
2.0 using LSC 3.0. They don't work! Although they compile OK, 
the call backs to Hypercard don't seem to work all the time. For 
example, 


paraemPtr-?returnValue = (Handle) CopyStrToHand(*A string"); 
always gives an empty hypercard XFCN result. Anyone 


have any ideas about what on earth I am doing wrong? 


From: Siegel 

Subject: C-ing is not believing! 

In TLSC 3.0and later, strings are treated as global variables, 
rather than being placed pc-relative. Therefore, you need to do a 
RememberAO() and a SetupA4() at the beginning of your main, 
and a RestoreA4() at the end. The same applies for floating-point 
constants. 


From: Apage 
Subject: Smalitalk/V Primitives 
I am about to embark on some development with MPW 
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assembler to generate a new set of floating point primitives for 
Smalltalk/V Mac. By using TMON to set a trap intercept for 
_FP68K I found that Smalltalk is still trapping through SANE to 
get to the 881 processor. Iam interested in seeing if I can generate 
faster primitives in Assembly that will address the coprocessor 
directly. Iam doing this both to see if there is benefit to be gained 
and to get the feel of the interface in Smalltalk and its primitives. 
Would anyone be interested in my results and experiences? 


From: Noisy 

Subject: SysEnvirons help? 

OK: so not all of us rush out and buy MPW 3.0 as soon as 
it’s released. Can anyone help out a (starving) LSC coder by 
revealing the SysEnvirons codes for the MacSE/30 & МасПсх? 
Pretty please? 


From: Batista 

Subject: My DA drawing don’t work! (sob) 

Check the messages on C, there was a similar case. The work 
around is to declare your own gray pattern. 


From: Sped 

Subject: Dialog Redrawing 

In every serious application I’ ve ever written, I’ve run into 
this problem. Inevitable, I write a “FlushUpdates” procedure that 
goes thru each of my windows and redraws those that have non- 
empty updateRgn's. For dialogs (modal and otherwise), a call to 
DrawDialog does the trick. Clears up all kinds of ugliness, such 
as when one modal dialog appears in front of another. 


From: Skarosx 

Subject: Ihe 

This is a neat board. А lot of programming info in one place 
is a time saver. I downloaded some of the code snippets and have 
been trying to install a VBL task as init. Well, I ran into a small 
problem. To geta VBL to live in the system heap, it seems I have 
to get a pointer to a block in the Sysheap. Then I can blockmove 
the VBL code to that pointer. After speaking with the helpful 
folks at Symantec, the call one needs to make in pascal has to be 
defined in assembly or with inline code. No problem, it is: 


Function newPtrSys (N: longint): ptr; 
Inline 


$201F, $45 1E, $2E88; 

Mucking around with the system heap got me nowhere, so, 
I tried to get the technique to work with the application heap. 
First, an innocuous VBL task (something that just posts an APP1 
event) is compiled separately as a code resource with a specific 
ID. Second, an application is written to install this VBL code in 
the application heap, and then the application checks for APP1 
events in its event loop. The commands to set up the VBL are: 

resH := GetResourceC'CODE^, 600); (This TcodeT resource) 

(with ID = 600 contains the compiled VBL task ) 

Hlock(resH); (Lock the handle) 
resSize:= GetHendleSize(resH); 
Aptr := newptr(resSize); (Get a pointer on the appHeap to 
a block big enough to accomodate theTcodeUresource) 


Blockmove(resH^, Аріг, resSize); (Move the TcodeU tothere) 
The rest of the application finishes setting up a simple menu 
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and window and the VBL is set up with: 


VBL_ptr := @vbl_rec; 
With vbl_rec Do 
Begin 


qType := ord(vType); 
vblAddr :- resH*; (the VBL task is a code resource 
(moved into the address at sysptr) 
vblCount := 60; 
vblPhase := 1; 
End; 


os_result := Vinstall(VBL ptr); ` 

With this program , all I get is one interrupt. Quitting the app 
gives me 'gerr' ,ie., the task is not installed! Help! Stegfan 
Karos 


From: Nicks 

Subject: VBL 

Sounds like you're not setting the vblCount back to а non- 
zero value inside your VBL task. A quote from ІМ: ““VBLCount 
specifies the number of ticks between calls to the task. This value 
is decremented each [tick]" until itis zero, then the VBL task will 
be called “The task must reset VBLCount, or its entry will be 
removed from the queue after it has been executed." 


From: Skaros 

Subject: VBL 

Right! My guess as to what is happening is that my vbl 
counter that is supposed to be initialized during every cycle of the 
VBL task with the statement—vbl rec.vblCount := 10; really 
isn't working. After all , how can a VBL task that is moved into 
a heap with “‘blockmove’ ever know where its VBL record is. 
Therefore, it doesn’t reset its counter and therefore it expires after 
one interrupt. How do I pass the address of the VBL record used 
in the installer program to the VBL task so that after the VBL is 
installed, it resets its counter? Or, is there another way to set up 
a VBL task as an init? 

Stefan Karos 


From: Rdclark 

Subject: Scrolling 

Using SetOrigin() is probably the worst possible way to 
do scrolling, as it causes your sroll-bars to flicker and generally 
behaves in strange ways. If you are using object-oriented pro- 
gramming, as you imply, it should be easy to base your display 
objects on a "display device" type which contains the (virtual) 
top-left of the GrafPort and redraw all objects in relationship to 
that. Still, if you still want to use the SetOrigin method, drop me 
a line atrdclark@applelink.apple.com (or here as *rdclark"), and 
I'll dig up some code. 


From: Gurglekat 

Subject: Souping up TE 

Don Brown managed to soup up TextEdit for his terminal 
DA MockTerminal. I’ve put trap breaks on all the relevant TE 
traps, and he seems to be using TEInsert for everything but 
backspaces and TEKey for backspaces. I don't know why he 
made the distinction, because there doesn't seem to be any speed 
benefits. Maybe there are on the 8 MHz Macs. But in any case, 
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when I use the same strategy in my code, the screen i/o can barely 
keep up with 300 baud, if that. What’s DB’s secret? I sure don’t 
want to write a TE clone. 


From: Frankh 

Subject: Souping up TE 

If you want to use TextEdit to display data any faster than 
300 baud, you'll have to buffer the incoming data, giving time for 
TE to digest it. The easiest way to do this is to increase the serial 
port input buffer size to something reasonable - the default 64 
byte buffer just isn’t enough. Use SerSetBuf to increase this 
buffer to 512 or 1K bytes. Don Brown is probably using TEKey 
to backspace over text that already has been displayed and is no 
longer in his buffer. It’s the easiest way. 


From: Gurglekat 

Subject: Souping up TE 

Hmmm. Well, what I meant about the distinction was that I 
wondered why he used anything but TEKey. Whatever. Now, 
what’s this about buffering data? I’ve got a 10K serial buffer. 
Should I only get characters from it when it's full toa certain level 
and then get a lot of them? At the moment I'm getting a character 
each time through the main event loop. And emptying the buffer 
entirely each time through the main event loops doesn’t seem to 
help either. 


From: Frankh 

Subject: Souping up TE 

If you use the SerSetBuf function to increase the serial port 
buf, then all you have to do is do a SerGetBuf (which returns the 
# of bytes in the input buffer) once through the main event loop. 
If the input buffer (the one increased with SerSetBuf) has data in 
it, just read off however many bytes were received (usually into 
another buffer) and process them at your leisure. Since you may 
end up with more than one character, its easier to display this data 
by using TEInsert. Usually, you’ll handle backspace and other 
control characters before you sent the buffer out to TEInsert, but 
if you only have a BS in the buffer, then you have to use TEKey 
to make TextEdit backspace for you. TEInsert ignores BS. 


From: Gurglekat 

Subject: Souping up TE 

Not only does it WORK, but it works in a neat way. As soon 
as I added the scrollbar for the scrollback buffer, I had to update 
the scrollbar control bar max and the value to match every time 
a new line came in. So now, instead of the output jerking along 
like some sad approximation of multitasking, most of the buffer- 
ing goes on during the new line sequence, so lines appear all at 
once but partial lines are also taken care of! Thanks again. 


From: Inbox 

Subject: Scrolling 

I'malso very much interested in getting some good scrolling 
code. I'm writing a spreadsheet-type of thing, and I can't redraw 
the whole screen every time - takes too long. So, please e-mail 
any scrolling code at all. Thanks in advance, 
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From: Cheasy 

Re: INIT31 Help wanted 

Today I’m writing because of some VERY difficult pro- 
gramming problems. At this time, I am trying to write an INIT for 
use with the INIT 31 mechanism, which will do something like 
pop up a dialog box onto the screen. (Yes, indeed, I need this 
during startup!) 

Unfortunately, if I call InitWindows from the toolbox, the 
startup screen is destroyed and the menu bar will be drawn, along 
with a fresh erased desktop. This is an very ugly effect, especially 
if there are more than one or two INITs in my System Folder. So 
I wrote some code to draw some pseudo-dialog boxes, fill them 
in, handle something like EditText fields and look for 
mouseDown events in different regions. They all work nice in my 
testing program. To make them work, I have to initialize a lot of 
low-memory globals myself, including my own quickdraw glo- 
bals. This all worked fine. 

But when I try to CopyBits the background of my window 
before drawing onto it, the routine will crash immediately. 
Nothing works, and even my own QD globals seem to be 
destroyed. Has anyone out there a little bit experience dealing 
with quickdraw at startup (INIT31) time? I am interested in any 
code which shows how to set up and reference to Quickdraw 
globals at INIT time. 

P.S. I apologize my bad english, but in fact, I am only 
speaking Pascal. (You can ask me for a German version of this 
bulletin.) 


From: Anthony 

Re: INIT resources 

Ihave a question, I am working with INIT's, and just wanted 
to see if this bit of code would really do the job. It is written in LS 
C, and is all of one line, 


mainC) 


Sysbeep(5); | 
) 


I have saved it as an INIT, but when I add it to the list of INIT 
resources in the system, and reboot, it doesn’t do anything? Why, 
I don’t want to use the INIT 31 trick, I want this to be a part of the 
system file, so I don’t have to worry about users carrying it over 
with them when they switch pc’s. 


From: Retzes 

Re: INIT resources 

I think there are two possible reasons why the INIT didn’t 
work. One, at the time the init is called the Sound-manager, 
Operating-System Utilities, or Sound-Driver has not been initial- 
ized. Two, the INIT didn’t get called for some other reason. 
When making an INIT that uses Quickdraw functions, I think you 
have to call InitGraf with a pointer to some local variables that 
resemble the Quickdraw globals. This was what seemed to be 
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necessary when I added a function that displayed the ICN# for the 
INIT at the bottom of the screen at startup. I found out how to do 
this with TMON, examining another INIT file. First you must 
decide what you want your INIT to really do, then decide if its 
possible with the system existing at startup. 


From: Mikec 

Re: New folders from HyperCard 

Is there any way to create new folders form within Hyper- 
Card using an XCMD? I have a HyperCard application that needs 
to create a new folder with the user's name every time a new user 
registers. There is nothing in “Inside Mac.” or the Mac Tech 
Notes оп this. Is this a closely guarded secret of the Mac's finder? 
Thanks for any info or support. 


From: Tonys 

Re: INIT using dialog manager 

How до I create an INIT using LS Pascal which accesses the 
dialog manager, such as a simple StopAlert call? I think I know 
how to access the Quickdraw globals using CurrentAS, but once 
the dialog has been dismissed, the system bombs. Am I missing 
some other initializations or have resources labeled incorrectly? 


From: Slegel 

Re: INIT using dialog manager 

You'll need to call InitWindows, InitFonts, and InitDialogs 
as well. It's generally un-INIT-like to fire up the Window 
Manager. If you want to give a message, use ShowlInit to draw 
your INIT's icon with an X in it, or something similar. 


From: Rguerra 

Re: KeyMap Kraziness 

Can someone PLEASE help me with manipulating the 
keyMap and modifier keys in assembly? I have user-definable 
modifiers stored (derived directly from the event record's modi- 
fiers field. I know that the modifier keys all live in bytes 6 and 
7 of the keymap. І can easily MOVE these bytes toa data register, 
but I can’t seem to figure out how to manipulate the bits of either 
the stored modifiers or the keyMap bytes, and then determine if 
they are the same. I have to do this directly in assembly since this 
is ina patch. I know that this will only take about 4 lines of code, 
but I can't quite get it right. (It's so frustrating since I can do the 
check so easily in Pascal.) Can someone help? I'd appreciate it. 


From: Gurglekat 

He: KeyMap Kraziness 

Give the BTST instruction a whirl. I'd tell you more about 
it but my Motorola 68000 manual seems to have escaped me. 


From: Siegel 

Re: More Help 

To create your own port and fill up black, try this: 
ташы; 


GrafPort muPort; 
Ini tGraf (kthePort); 
OpenPor tC &myPor +); 


/* static storage */ 
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PaintRect(&muPort.portRect); 
) 


From: Apage 

Re: More Help 

Your most obvious problem in this code is your calls to 
EraseRect and FrameRect. 

The Pascal trapsare expecting them to be passed as a Pointer 
torectangles,howeverthe C compiler willtry passingall 16bytes 
of each rectangle onto the stack, as per C calling parameters. 
Change your calls to the following and try again: 


EraseRect(&muPort.portRect); 
FrameRect(&myPort.portRect); 


From: Bcbg 

Re: More Help 

When you call the ROM in C, you must be aware of the 
standard calling conventions.Every object more than 4 bytes in 
size or every VAR parameter is passed by “address” and not by 
"value". It means that to call EraseRect, you must do: 


EraseRect (&myPort .portRect); 
Same thing for FrameRect. If you used LSC 3.0 or MPW C 


3.0, the compiler would tell you these problems... 


From: Cforden 

Re: LSC Assembly: Save registers for call? 

What registers must I save before I call another routine? 
Inside Mac (phone book ed.) and LSC (3.0 manual) both hint that 
registers DO-D2 and A0-A1 are generally considered expendable 
and are generally trashed by routines. However saying that they 
(LSC and the toolbox) trash them is not quite the same as saying 
Iam allowed to trash them or let them get trashed. In fact I found 
that if I did not save those registers prior to calling my LSC 
wordBreak() routine and restore them upon return, the toolbox 
would get confused and crash the system. I couldn't find explicit 
guidance in Williams' book "Programming the Macintosh in 
Assembly Language" (Sybex), but many examples showed all 
registers being saved by routines. 


From: Noisy 

Re: LSC Assembly: Save registers for call? 

Hmmmm...I thought that the LSC (v3.x) manual (pg. 151) 
was pretty clear about saving DO-D2/A0-A1, and ІМУІ says the 
same. As for what an application can trash, I haven't had any 
problems trashing registers prior to Toolbox calls. Like yourself, 
though, I did get into trouble with ‘call-back’ routines: routines 
that are provided by the application, but actually called by the 
Toolbox. (The one that bit me was a List clikLoop) I have 
adopted the “better safe than sorry' attitude of pushing/popping 
ALL registers in call-back routines, just to ensure future compati- 
bility if nothing else. The space and time wasted by pushing 
registers is nothing compared to the agony of trying to figure out 
which one got trashed by whom! 


From: Siegel 
Re: LSC Assembly: Save registers for call? 
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The conservative way to go is to save any registers you use, 


, andifany routines that you call use them, be sure they're correct. 


From: Bruceq 

Re: Alternate Screen/Snd 

Iamcurrently writing a game for the Mac and need to use the 
Alternate Screen/sound buffers to make it playable on non 020 
machines. I know that I can use the alt. buffers if I force the user 
to boot off of the master disk, but I would really like to have the 
game load off of the users harddisk if possible. The problem is 
the case of MultiFinder running. Does Launch still allocate the 
alt buffers for you when asked? What if another program had 
loaded previously? Will MultiFinder reserve that space or swap 
itout if the foreground application needs the alternate buffers? Or 
has Apple decided not to support the alt buffers in the future. I 
don't need to use a frame buffer on a 68020 or 030 machine 
because of the extra HorsePower, but doing full screen animated 
graphics on a Plus or SE with out the frame buffer is the pits. 

Any ideas or higher knowledge? 


From: Gurglekat 

Re: WMgrPort ?'s 

There is a low memory global called DeskHook, $A6C, 
which according to my Inside Mac X-ref is “Address of proce- 
dure for painting desktop or responding to clicks on desktop." 
You might ask jbx, whose CompuServe address is 73177,1404, 
how he did the pop-up menu bar in hierDA — I'm pretty sure he 
used this routine. If not, you might want to contact the DeskPict 
people. 


From: Gus 

Re: ANIMATION 

Hey there guys. I'm writing a freeware game for the MAC 
and am interested in how you guys do flicker free animation?? 
I've tried everything. Is there some secret I don't know about?? 
Code would really be appreciated. Also I'm using a Mac+ and 
I'm, writing in LSC. I would really appreciate any help as you 
guys are my last hope before that programming black hole. 


From: inbox 

Re: ANIMATION 

You can read about it in Scott Knaster's ‘How to Program 
Macintosh Software'. Anyway, here's the advice given there: 
(I'll condense it...) It says that the first thing that occurs in the 
vertical retrace interrupt, is that the global variable Ticks gets 
incremented. So you can draw right after the interrupt occurs, 
before the beam actually draws the stuff on the screen. So, here's 
the suggested code of your drawing proc: 


Var tickValue : longint; 
begin 


tickvalue := TickCount; (calls ROM to get value of Ticks) 
repeat until CtickValue € TickCount) 


( start drawing fast!! here...) 
That loop waits until the interrupt occurs, and then you 


should draw. Keep in mind that the top of the window should be 
drawn before the bottom (if possible) because the electron beam 
goes from top to bottom. 
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From: Tan 

Re: Scrolling 

What you could do is to use ScrollRect, that'll take care of 
most of the window that's scrolled. The new portion of the 
window contents that need to be redrawn can be clipped. As 
there's less to draw on the screen, it would be faster. Of course, 
another way is to cache a margin around the current visible area 
in an offscreen bitmap and blit it in when you scroll to the cached 
area. You’ll need four caches for each of the four directions you 
can scroll in. I think Excel does something like that to speed the 
scrolling. 


From: Moreno 
Re: Scrolling 
Here is some pseudo code for determining if you should 


draw a line in your apps window 

theUpdateRgn := NewRgn; { create a temporary region, NewRgn 
returns a region HANDLE } 
ScrollRectCwindowRect Minus One.Line.st Top.Or.Bottom, + _or_- 
_One_Line_Height, 

0, theUpdateRgn); 

( don’t forget to subtrac the scrollbars from the window rect 


) 

trect:2theUpdateRgn^ ^ .rgnBBox; 

SetRect(DrawingRect, ( you fill in the blanks it’s not MY 
program) left, top,right, bottom); 

IF RectInRgnCOrawingRect, YourWindow^.visRgn? AND 
RectInRgnCOrawingRect, 

YourWindow^.clipRgn) THEN 

BEGIN 

( draw the top or bottom line if scrolling by on line } 
END; 


From: inbox 
Re: TEdit 
Does anyone know of a good way to replace (or designate) 
the text in a Text Edit record? I did the following, and it didn’t 
quite work... vat sheesh.. make that VAR 
myTeh : TEHendle; 
myStrHandle : StringHendle; 
myStr : String(20]; 
begin 
myStr := ' 20 letters go here... '; 
myStrHendle := NewString(myStr); 
nyTeh^^.hText := Handle(myStrHandle); 
TECalText(CmyTeh); 


end; 
What happens is that a garbage char gets displayed along 


with the first 17 or so characters of myStr; And the ASCII value 
of the char is 20, and so is the length of the string. So, I think that 
the type coercion from StringHandle to Handle makes it point to 
the length of the string and not to the contents. I don't know what 
to do with this, because I' m using LSP 2.0. If this was in C, no 
problem. But I don't know how to do this in Pascal. So, I 
FOUGHT THE ROM AND THE ROM WON!!! «asobisheard 
here» ANY suggestions are greatly appreciated. 


From: Gurglekat 


Re: TEdit 
Just in case you've not got an answer yet, the garbage 
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character is the Pascal length byte. NewString passes you back a 
StringHandle, which points to a chunk of mem headed by the 
length byte, which is followed by the letters of the string. In order 
to do what you are doing while maintaining your code, it might 
be best to do 


BlockMoveCémyStrHandle^^[1], 
length(myStr22; 
SetHandleSizeCHandle(myStrHandle)), 


HandleCmyStrHandle))-1); 


@myStrHandle**(8], 
GetHandlesize( 


before installing the handle and TECalText' ing. However, I 
think you should use 


TEInsertCémyStr [ 11, lengthCmyStr), myTeh); 


which avoids the StringHandle muddle altogether. TEInsert 
will take care of space for the text, if that's what you're worried 
about. 


From: Gurglekat 

Re: TEdit 

Ah. Forgot to mention — the TECalText becomes unneces- 
sary if you use the TEInsert method. 


From: Inbox 

Re: TEdit 
I thought that this was the garbage char. Thank you very much 
for your suggestion. However, I don't think that TEInsert is 
the way to go because I have to clear the text that was already 
there. Anyway, I' m using this scheme in a spreadsheet program 
I'm writing (and, no, I don’t plan to put Microsoft out of business) 
for input to and from cells. The new text has to be shown when 
a new cell is selected, and that’s where the garbage char problem 
comes in. Is there a better way to do cell input? 


From: Pdyson 

Re: Shutdown under Multifinder 

A good Multifinder-friendly app quits gracefully when the 
user gives the Restart or Shutdown command from the Finder's 
Special menu. But what is the secret of writing an app to receive 
and obey this message from the Finder? I downloaded the 
TEsample.C from Apple DTS, modified it for LSC 3.0 and Lo! 
it simply refuses to die when the Finder calls for a restart. 

The app has 4 mstr resources (100-103) and (since I simply 
cribbed it from DTS) should be correct in the way it dispatches 
events. I am mystified. 


From: MacDTS 

Re: Shutdown under Multifinder 

I would guess the “Quit” item in the File menu has more than 
what you're specifying іп ‘mstr’. Look for some spaces after the 
Quit string. I've heard about this problem before with LSC. 


From: Rapler 


Re: GrowZone, cbNeeded 
I've gota GrowZone proc that seemed to work fine, except 
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that, occasionally, I get a negative number for cbNeeded. I’m 
using LSP 2.01, and my test program is allocating $9000 bytes. 
The value of cbNeeded is FFFF9008!! Is this an OS bug, a 
weirdness with LSP’s Zone, or something unheard of??. 

I don’t want to add a special negative number handler 
without knowing why, and I want to put off going into Macsbug 
if someone already knows what’s happening. 

Any help would be appreciated. 


From: Brad 

Re: GrowZone, cbNeeded 

How are you allocating the memory? If you are using $9000 
as a constant, try changing it to $09000, which will force the 
Compiler to use a LONGINT. It might be sign extending the 
$9000 (which is -28672 in decimal), in which case you would be 
asking for a HUGE block of memory. I think the memory 
manager treats memory requests as unsigned. 


From: Nfong 

Re: ioFLAttrib 

I’m trying to set the protect bit in ioFlAttrib with PBSet- 
CatInfo but can’t seem to get it to work. It returns with no error 
but doesn’t do anything. Anyone got any suggestions? 


From: Inbox 

Re: bundle bit 

Does anyone know whether it’s possible to set the bundle bit 
using ResEdit? I’m using LSC 3.0, and couldn’t get the icon to 
be recognized. 


From: Spud 

Re: bundle bit 

There was an old version of ResEdit that had the Changed 
and Bundle bits mixed up; you clicked on the Bundle checkbox 
and the Changed bit was set, and vice versa. The good ol’ boys 
at Apple have fixed that little mishap since then, and I’m sure that 
the version here (version 1.2) has the fix. 


From: Eau 

Re: bundle bit 

Yes, you can set the bundle bit with ResEdit. Do ‘command- 
Г when а file is selected, and a window will appear, which has a 
checkbox for Bundle. To get the Finder to recognize the icon, you 
will probably have to move the file to a different folder. The 
Finder will not automatically pick up changed bundle bits. Of 
course, the file should also contain resources defining the icons. 

When I've got an application, and I want the Finder to re- 
read the bundle information, I move it between the top-level and 
a subdirectory on my hard disk. This works pretty well. Hope this 
helps. 
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From: Willcox 
Re: Deleting a Folder 
I am having trouble deleting a folder using the Low Level 
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File Manager routines. I have created a folder and put some 
temporary files in it. At the end of my program, I would like to 
delete this directory. I am trying to use PBHDelete. I first delete 
all the files in this folder. Then, I try to close the working 
directory with PBCloseWD since I opened it with PBOpenWD. 
Then I call PBHDelete. I get error -47, fBsyErr, File is busy. I 
have tried various parameters in PBHDelete (WDid, vRefnum, 
name of folder), but I still get -47. Also, when I do this with 
MultiFinder turned off, I can not delete the folder from the 
Finder, it too says the folder is busy. Help. 


From: Adept 

Re: Deleting a Folder 

When doing any PBOpen calls, you have to be sure to set 
your ioWDProcID to ‘ERIK’, the magic ‘longint’, otherwise it 
will be undeletable by the finder (until reboot), You might be 
calling PBClose with something != PBOpen and != to 'ERIK'.. 


From: Mikec 

Re: Setting current folder 

Bryce, I am excited to see your message #878 that creates 
new folders. I have been wanting to do this for an application for 
along time. But I am just starting to program and have little idea 
how to fit your listed code into a procedure that will create the 
folder. Can you help me by listing a more complete procedure or 
uploading a text file? I use LSP and would be delighted to hear 
from you. 


From: Tony 

Re: Setting current folder 

Mike, Below is the list of a function call CreateFolder. I 
believe this will do what you want. It takes as parameter the name 
of the folder and the volume reference of where to put the folder. 
In return, it will pass back and errorcode and the FolderID. The 
folderId is in fact the Directory Id and can be used a vRefNum 
(volume reference no) in any of your File I/O calls. 


Function CreateFolder(FolderName:str255; vRefNum : 
varFolderId:longint2:0SErr; 
Var 
Blk :HParamB lockRec; 
errorcode :05Егг; 
begin 
with blk do 
begin 
ioCompletion := nil; 
ioNemePtr := eFolderName; 
ioVrefNum := vRefNum; 
ioDirId := Ø; 
end; 
errorcode := PBDirCreate(@blk, false); 
FolderID := blk.ioDirId; 
CreateFolder := errorcode; 


end; 


integer; 


Hope this helps. 


From: Shaper 
Re: List Manager problem... 
Does anyone have any source code for the List Manager 
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routines? I got the source to the LDEF”s in the Think Pascal 
library on CompuServe and tried to use that source but it's kind 
of strange because he used custom LDEFs with variable column 
numbers. I want to use the LDEF that comes in the system file 
to make a list of people’s names, and I can get the list to appear 
but the only way to scroll it is to click on someone’s name and 
then drag downward to scroll down - the arrow buttons don’t 
work for some reason. Also, it doesn’t always hilite the cell that 
you click on, so you have to keep clicking on different parts of the 
list cntl until one does hilite before you can scroll up or down... 


From: Jumpcut 

Re: List Manager problem... 

If you don’t specify a LDEF, the List Manager will use the 
standard system LDEF. You can then set the list’s selFlags to 
make sure things get selected properly. CHeck around page 270 
of IMIV. I was having similar problems after I changed the font 
and style of the window the list was in. First thing to check - make 
sure your window is a noGrowDocProc, or else the grow box 
(whether you draw one or not) will keep mouseDown events 
from scrolling the list down. I’m sure you're using LClick, so I 
won't bother to mention that. My only other suggestion is to 
avoid the obviously stupid (unlike me) and remember to change 
the font & face before creating the list. 
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From: Jmoreno 

Re: Dispatch Table 

I’m trying to gain some experience with C by translating a 
program I have from Pascal to C. I don't want to do a line by line 
translation, and I noticed that I could handle menu events using 
a dispatch table to functions instead of a bunch of switch 
statements. My problem is that I can not get the dispatch table to 
compile under Think C 3.0. Could somebody please post an 
example of one? 


From: Noisy 

Re: Dispatch Table 

One way to code a dispatch table in C is to create an array of 
pointers to functions. That way you can provide your own 
indexing techniques and bypass multiple depths of switch() 
statements. This does have some limitations though: since all the 
calls are made through a single statement, ensuring that each 
function gets the correct type/number of parameters can be a 
headache (typecasting unsigned longs is probably your best bet). 
Secondly, heaven help you if you try to jump with an invalid 
index value...you’ll discover the delights of the BRND (Branch 
to random address) opcode! Anyway...here's a little source to 


help you on your way: 
typedef void C*FuncPtr2(); 
FuncPtr func .list(] = (ту funci, my func2, mu-func3 ); 


index. val = 2; /% whichever value you want to jump to 
(*func-list[index_val]))(parameters...); 


Eh voila! Instant jump table. 
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From: Gpoole 

Re: INITs 

Thisisafairlyopen-endedquestion but we would appreciate 
any help we can get on this matter. The subject is INIT’s, or more 
specifically, how to get along with them. We are developing a 
program for commercial release and all seems to work fine as 
long as we are using just Finder or MultiFinder, no bombs, errors, 
weird happenings, quitting unexpectedly, etc. As soon as we 
have some INITs in the system though, all kinds of weird things 
start happening. With that said, are there any general guidelines 
we as developers should follow in coding to peacefully co-exist 
with INITs? Are there any known defensive programming 
techniques? In case it helps, some the INITs we have are: 
DialogKeys (CE Software), SuperLaserSpool, PowerMenus, 
Capture, CanOpener, and Suitcase. Thanks for any help you can 
give. 


From: Gurglekat 

Re: INITs 

The only thing I can think of for general defensive program- 
ming against INITs is to assume that ALL traps move memory. 
Patched traps can, of course, move memory, and INITs patch 
traps... I don’t remember where I heard this; maybe from one of 
Knaster’s books. 


From: Rguerra 

Re: INITs 

It’s probably SAFEST to assume that ANY trap can move 
memory. While a patched trap’s code in and of itself doesn’t 
absolutely HAVE to move memory, there are no guarantees. If 
you’ re going to patch traps, one should avoid appending code that 
moves memory in a trap that is NOT supposed to do so. But who 
knows what goes on so ... Let's all be careful out there! 


From: Gpoole 

Re: INITs 

Thanks for the replies to my INIT question, especially the 
one from DTS. Ialsoasked them this same question and the reply 
was that there is nothing that can be done for defense. The 
trenches seem to know best. 


From: Brad 

Re: INITs 

If your program doesn't get along with the INIT's you 
mentioned in your message, then either you have a knack for 
finding bugs in other people's code, or your program is doing 
something very wrong. I work on a very large commercial 
product, and I run with dozens of INITs, MultiFinder, EtherTalk, 
etc, and darned near all of the crashes I see are either bugs in my 
code or bugs (occasionally) in the system. Some INITs out there 
are downright dangerous and shouldn't be distributed, but many 
of those you mentioned could be considered standard equipment 
on many machines. 


From: Brad 
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Re: INITs 

It's ridiculous to program as if any trap can move memory. 
If someone patches a trap that is documented as NOT moving 
memory, and, as aresult of something in the patch, memory may 
be moved, then the patch has a bug and shouldn’t be used. 
Defensive programming is important; check your error codes, 
preflight, don’t assume, etc - but there’s no need to get carried 
away. Relocatable blocks don’t relocate unless provoked, and 
they only get purged if they’re purgeable and memory is tight. 
(But come System 7, and who knows...) 


From: Gurglekat 

Re: INITs 

It’s not the tough to program as if any trap can move 
memory. All you really have to be careful of are WITH state- 
ments, keeping handles half-dereferenced across traps, and pass- 
ing dereferenced elements of records in handles as VAR parame- 
ters. HLock and HUnlock aren't that hard to use. 


From: Essam 

Re: Simple INIT 

There was a beautiful example of an INIT that stays around 
(by patching GetResource and ExitToShell to beep when an 
application is launched or quit, found in MacTutor June 1989. 
Unfortunately, this INIT was in Forth. Does anyone have a LSP 
Pascal version of this code? 


From: Inbox 

Re: LSP I/O procs 

It seems that LSP’s built-in I/O procs don’t work properly 
with HFS. My app uses info passed by SFGetFile in the 
Open(myFileVar,name) call but I can’t access files that are in a 
directory other than the one the app is in. What should I do? Do 
I need to use PBGetCatInfo or something of this sort?! 


From: Slegel 

Re: LSP I/O procs 

IF you’re getting back from a standard file call, do a 
SetVol(NIL, reply.vRefNum) before calling the library routines. 


From: Unclejim 

Re: Disk Based Scrolling 

Help! I am still struggling with getting some disk based 
scrolling to work. I need to scroll around in 200-300K files and 
only keep 40-50K in memory at one time. (Scroll Up & down 
etc). I can't seem to keep my scroll bars moving smoothly as I 
swap buffers and use TESetText etc. If anyone has even the 
simplest example of this disk based scroll in any language it 
would be a terrific help. Editing is not an issue at this stage just 
scroll up and down and keep track of the buffers. I thought it 
would be easy; it probably is, but I’m not having much luck so far. 
Thanks Jim 


From: Jmoreno 
Re: arrays as files 
Here is some pascal source for finding you were launched 
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with a file 

CountAppF i lesCAppMessage, NumAppFiles); 

IF NumAppFiles <> 0 THEN ( the user has opened documents from 
the finder ) 

thet would be something like 

CountAppF ilesCAppMessage, &NumAppF i les); 


if NumAppFile != 0 /* open the file */ 
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From: Willcox 
Re: Print Manager Error 
I solved my printing problem, but I do not fully understand 
why it now works. Maybe someone out their can explain. First, 
the problem was that sometime when printing (using a Mac IIcx 
only), the system would sometimes forget that a certain font was 
a LaserFont, and promptly started creating a bitmap for it. 
However, the screen font information was also lost, so this 
process eventually terminated in an error. 
I tracked the problem down to a single call to "UseResFile" 
from which I had to load a specific private resource. I fixed the 
problem by 12. the code to: 


temp :=CurResF 
UseResF i Tet heb leNumber ); 


theResource : -Ge tResource(asdf jasldf ); 
UseResF i le( temp); 
Now, why does this work??? Ihave not found a warning in 
Inside Macintosh, and the error only occurs on my Mac IIcx, not 
on my Mac Plus. 


From: Jmoreno 
Re: Print Manager Error 

What was happening is the call to UseResFile wasremoving 
the System from the list of open files to search for a resource. And 
that font was no longer found. The system adds each opened 
resource to the end of a list and then when you try to load a 
resource it starts at the end and backtracks looking through all of 
the open resource forks for the requested resource. So when you 
open a resource it gets a place in line, when you call UseResFile 
it gets put at the beginning and is set to be the FIRST resource to 
search (everything else is then gone from the resource list). Hope 
this helps you understand what is going on. BTW if you haven't 
already ISTRONGLY recommend that you buy Inside Mac Vol 
1 to 5. 


From: inbox 
Re: Var declaration 

Sheeshh.... Here I go again.. 

Awright, I' m trying to create an array of the following size 
after VAR in my globals unit: myarray : array[1..7,1..300] of 
string[20]; but LSP says that it'S "unable to create 
blah..blah..blah on this level". Now whatis a body to do if using 
dynamic memory allocation means changing the whole pro- 
gram?? Is there some kind of a call Ican make to perhaps increase 
the size of the applications stack beforehand?! But the globals' 
unit gets compiled first so the instruction won't get executed at 
that point... 

Thanks for listening, 


_inBox_ (this should read  in- 
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Trouble_) 


From: Jmoreno 
Re: Var declaration 
In the run options part of Think Pascal (formerly LSP) there 
is an option for setting both the stack (which is what you want) 
and the heap. 


From: Tomt 
Re: Var declaration 

Dumb question but how in Pascal do I access the stuff in a 
handle. My problem is that I need to make an array of integers 
of size, say, 500 by 500. Now I tried array type of that 
size,without making any instances of it, but LSP wouldn’t let do 
that. So if I make a handle to the appropriately sized chunk of 
memory, how do I access the i,j the element. I’m sure its trivial, 
but I haven’t been able to figure it out. Thanks in advance for any 
help 


From: inbox 
Re: Var declaration 


Awright.. Methinks I got it.. Here's the 500 by 500.... 
TYPE 

myarray = arrau[1..500,1..500] of integer; 
myarrayptr = “myarray; 

myarrayHandle = “myarrayptr; 
VAR 

THEarray : myarrayHandle; 
BEGIN 


THEarray := myarreyHendleCNewHandle(SizeOf (myarray2)); 
That's it. To access an element, do 


myint := THEarray^^[ij]; where i and j are integers, etc... 
Set an element by THEarray^^[i,j] := myint; 
Hope this helps. | inBox 


From: Jimm 
Re: Var declaration 
On page 447 of LSP 2.0 manual it says that data structures 
cannot exceed 32766 bytes. Your data structure is 22*7*300 or 
>42K. 


From: Dhands 
Re: Var declaration 

The previous VAR declaration will work as stated, since the 
data structure allocated at compile time is only a 4 byte handle, 
not the >40k array. The array is later allocated dynamically at 
run-time. 

For example: 

VAR 

good : BigHandle; (4 byte handle to huge, >32к, data) 


bad : ARRAY[1..40000] char; (»32k data won't fit here) 
The difference is that “good” has it's data on the heap (via 


NewHandle) and is only limited in size by the available memory. 
Where as “bad” is pre-allocated space in global or local areas of 
the heap which is limited to 32k. 


From: Shaper 
Re: Printing Samples? 
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One more question, does anyone have any Pascal (prefera- 
bly LSP) source code for printing to an Image Writer - text only, 
no graphics necessary, I tried to use PrCtlCall() or whatever it's 
called, but I don't know how to set up a ptr to text, and also how 
do you set the HiWord and LoWord of a longint? I know you can 
GET it by doing aLongInt:2HiWord(bLongInt) or 
aLongInt:=LoWord(bLongInt) but you can't do 
HiWord(bLongInt):=aLongInt... 


From: Dhands 
Re: Printing Samples? 

Here’s a quick summary of draft printing using the print 
manager’ 5 low level calls. The low level calls should not be used 
for “real” printing, but they are great for quick-n-dirty printing. 

PrDrvrOpen; (open print driver) 

PrCt1CallCiPrDevCtl, 1РгВеѕеї, 6,0); ^ (reset/init printer) 


АКА Sha Kok аа some 
text 
лл ны (advance printer pa- 
per 
PrDrvrClose; 


(close print driver) 
VAR 
textBuf : PACKED ARRAY [1..256] OF Char; 


str қ Str255; 


Since you must explicitly advance the paper you have to 
print one line at a time. To print a Str255 for example: 


count := Length(str) (number of bytes to copy) 
FOR i := 1 TO count DO 
textBuf [i] := бігі11; (note: don’t copy over 51710) length 
byte 
PrCt1CallCiPrIOCtl, LONGINTC@textBuf 2, count, 0); 
PrCt1CallCiPrDevCtl, IPrLFSixth, 0,0); 


From: Jmoreno 
Re: Printing Samples? 

la) Why don't you try using the regular printing process, it's 
no big deal to open the port then open a page print a page, close 
the page then open another page if needed... 

1b) To get a pointer to the text in a Str255 use 

TextPtr:=@ YourString[1]; ( really need to make sure you 
have 1+ chars) 

2a) to set the Hi&LoWord of a longInt use: 

bLongInt:LongInt; 

theInt:^Integer; 

BEGIN 

thelnt:=@bLongInt; 

theInt^:» 12; ( set the HiWord) 

theInt:zPtr(LongIntCtheInt) + 2); 

theInt*:= 68; ( set the LowWord) 


END; 
or Use a variable RECORD 
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